From 76feaa8e101eb5f4b8f99799b7b229c638d98b5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Hohwiller?= Date: Fri, 29 Jul 2022 13:34:07 +0200 Subject: [PATCH 01/10] added date and time handling --- documentation/coding-conventions.asciidoc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/documentation/coding-conventions.asciidoc b/documentation/coding-conventions.asciidoc index 35f7424a..d1428c1b 100644 --- a/documentation/coding-conventions.asciidoc +++ b/documentation/coding-conventions.asciidoc @@ -77,6 +77,17 @@ This section gives you best practices to write better code and avoid pitfalls an === BLOBs Avoid using `byte[]` for BLOBs as this will load them entirely into your memory. This will cause performance issues or out of memory errors. Instead, use streams when dealing with BLOBs. For further details see link:guide-blob-support.asciidoc[BLOB support]. +=== Daten and Time +Avoid using `java.util.Calendar`, `java.util.Date`, `java.sql.Date`, `java.util.Timestamp`, or anything directly related. +Instead use types from `java.time` package. +The most important types are: +* `Instant` for an exact timestamp +* `LocalDateTime` for exact date and time but without timezone information. +* `ZonedDateTime` or `OffsetDateTime` for exact date and time with timezone information. +* `LocalDate` for a specific day (e.g. birthday). + +When mapping types to XML, JSON, database, etc. nowadays there is support for `java.time` so please *stop* using `Date` and `Calendar` and end the pain. + === Stateless Programming When implementing logic as components or _beans_ of your container using link:guide-dependency-injection.asciidoc[dependency injection], we strongly encourage stateless programming. This is not about data objects like an link:guide-jpa.asciidoc#entity[entity] or link:guide-transferobject.asciidoc[transfer-object] that are stateful by design. From d402f2f6ef227dedc0d68332e332040b3f4c7a1c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Hohwiller?= Date: Fri, 29 Jul 2022 13:36:01 +0200 Subject: [PATCH 02/10] improved data+time --- documentation/coding-conventions.asciidoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/documentation/coding-conventions.asciidoc b/documentation/coding-conventions.asciidoc index d1428c1b..8c948ef9 100644 --- a/documentation/coding-conventions.asciidoc +++ b/documentation/coding-conventions.asciidoc @@ -79,14 +79,17 @@ Avoid using `byte[]` for BLOBs as this will load them entirely into your memory. === Daten and Time Avoid using `java.util.Calendar`, `java.util.Date`, `java.sql.Date`, `java.util.Timestamp`, or anything directly related. +These types are historically grown, very error prone or to make it short a disaster. +Stop using them now! Instead use types from `java.time` package. The most important types are: + * `Instant` for an exact timestamp * `LocalDateTime` for exact date and time but without timezone information. * `ZonedDateTime` or `OffsetDateTime` for exact date and time with timezone information. * `LocalDate` for a specific day (e.g. birthday). -When mapping types to XML, JSON, database, etc. nowadays there is support for `java.time` so please *stop* using `Date` and `Calendar` and end the pain. +When mapping types to XML, JSON, database, etc. nowadays there is support for `java.time`. === Stateless Programming When implementing logic as components or _beans_ of your container using link:guide-dependency-injection.asciidoc[dependency injection], we strongly encourage stateless programming. From 51e3f5ac547a1e15d0b5ed73539dd498a44c389b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Hohwiller?= Date: Mon, 12 Sep 2022 17:26:21 +0200 Subject: [PATCH 03/10] Update guide-jee.asciidoc --- documentation/guide-jee.asciidoc | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/documentation/guide-jee.asciidoc b/documentation/guide-jee.asciidoc index d5ab9156..2a0f2e6a 100644 --- a/documentation/guide-jee.asciidoc +++ b/documentation/guide-jee.asciidoc @@ -11,6 +11,9 @@ Only if an existing Java standard is *not* suitable for current demands such as In all other cases we officially suggest the according standard and use it in our guides, code-samples, sample application, modules, templates, etc. Examples for such standards are link:guide-jpa.asciidoc[JPA], link:guide-rest.asciidoc#jax-rs[JAX-RS], link:guide-soap.asciidoc#jax-ws[JAX-WS], link:guide-dependency-injection.asciidoc[JSR330], link:guide-access-control.asciidoc[JSR250], link:guide-xml.asciidoc#jaxb[JAX-B], etc. +Please note that JEE has nowadays been replaced by https://jakarta.ee/[JakartaEE]. +link:quarkus.asciidoc[Quarkus] already supports this and also link:spring.asciidoc[spring]-boot starting with version `2.6` so for new projects you should consider to directly use only JakartaEE. + == Application-Server We designed everything based on standards to work with different technology stacks and servlet containers. However, we strongly encourage to use modern and leightweight frameworks such as link:spring.asciidoc[spring] or link:quarkus.asciidoc[quarkus]. @@ -23,9 +26,16 @@ Most application servers put you in a jail with old legacy technology. In many cases you are even forced to use a totally outdated version of java (JVM/JDK). This may even cause severe IT-Security vulnerabilities but with expensive support you might get updates. Also with leightweight open-source frameworks you need to be aware that for IT-security you need to update recently what can cost quite a lot of additional maintenance effort. +However, you are able to do so and react fast to new CVEs while for application servers it typically takes 10x more time to get CVEs out of your app. * *Development speed* + -With spring-boot you can implement and especially test your individual logic very fast. Starting the app in your IDE is very easy, fast, and realistic (close to production). You can easily write JUnit tests that startup your server application to e.g. test calls to your remote services via HTTP fast and easy. For application servers you need to bundle and deploy your app what takes more time and limits you in various ways. We are aware that this has improved in the past but also spring continuously improves and is always way ahead in this area. Further, with spring you have your configurations bundled together with the code in version control (still with ability to handle different environments) while with application servers these are configured externally and can not be easily tested during development. +With spring-boot you can implement and especially test your individual logic very fast. +Starting the app in your IDE is very easy, fast, and realistic (close to production). +You can easily write JUnit tests that startup your server application to e.g. test calls to your remote services via HTTP fast and easy. +Quarkus even increases this development speed. +For application servers you need to bundle and deploy your app what takes more time and limits you in various ways. +We are aware that this has improved in the past but also spring and quarkus continuously improve and are always way ahead in this area. +Further, with spring you have your configurations bundled together with the code in version control (still with ability to handle different environments) while with application servers these are configured externally and can not be easily tested during development. * *Documentation* + Spring and also quarkus have an extremely open and active community. @@ -73,7 +83,7 @@ We do not get paid from application servers nor from spring, quarkus or any othe We are just developers who love to build great systems. A good reason for application servers is that they combine a set of solutions to particular aspects to one product that helps to standardize your IT. However, http://www.devonfw.com/[devonfw] fills exactly this gap for the spring and quarkus ecosystems in a very open and flexible way. -However, there is one important aspect that you need to understand and be aware of: +But there is one important aspect that you need to understand and be aware of: Some big companies decided for a specific application server as their IT strategy. They may have hundreds of apps running with this application server. From dd3186d9cda0f31c92da84bc3fe483050b0b0c30 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Hohwiller?= Date: Mon, 12 Sep 2022 17:27:16 +0200 Subject: [PATCH 04/10] Update guide-jee.asciidoc --- documentation/guide-jee.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/guide-jee.asciidoc b/documentation/guide-jee.asciidoc index 2a0f2e6a..c7696d63 100644 --- a/documentation/guide-jee.asciidoc +++ b/documentation/guide-jee.asciidoc @@ -12,7 +12,7 @@ In all other cases we officially suggest the according standard and use it in ou Examples for such standards are link:guide-jpa.asciidoc[JPA], link:guide-rest.asciidoc#jax-rs[JAX-RS], link:guide-soap.asciidoc#jax-ws[JAX-WS], link:guide-dependency-injection.asciidoc[JSR330], link:guide-access-control.asciidoc[JSR250], link:guide-xml.asciidoc#jaxb[JAX-B], etc. Please note that JEE has nowadays been replaced by https://jakarta.ee/[JakartaEE]. -link:quarkus.asciidoc[Quarkus] already supports this and also link:spring.asciidoc[spring]-boot starting with version `2.6` so for new projects you should consider to directly use only JakartaEE. +link:quarkus.asciidoc[Quarkus] already supports this and also link:spring.asciidoc[spring]-boot supports it starting from version `2.6` so for new projects you should consider to directly use only JakartaEE. == Application-Server We designed everything based on standards to work with different technology stacks and servlet containers. From 778cd4dd656053d586df161845df9bc182d8033b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Hohwiller?= Date: Mon, 12 Sep 2022 17:48:07 +0200 Subject: [PATCH 05/10] Update guide-jdk.asciidoc --- documentation/guide-jdk.asciidoc | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/documentation/guide-jdk.asciidoc b/documentation/guide-jdk.asciidoc index 1a25f7ed..81fc21e2 100644 --- a/documentation/guide-jdk.asciidoc +++ b/documentation/guide-jdk.asciidoc @@ -21,8 +21,34 @@ As OracleJDK changed its licensing model and can not be used for commercial usag You may want to use OpenJDK for development and OracleJDK only in production. However, e.g. OpenJDK 11 never released a version that is stable enough for reasonable development (e.g. javadoc tool is https://bugs.openjdk.java.net/browse/JDK-8212233[broken] and fixes are not available of OpenJDK 11 - fixed in 11.0.3 what is only available as OracleJDK 11 or you need to go to OpenJDK 12+, what has other bugs) so in the end there is no working release of OpenJDK 11. This more or less forces you to use OracleJDK what requires you to buy a subscription so you can use it for commercial development. -However, there is https://github.com/AdoptOpenJDK[AdoptOpenJDK] that provides forked releases of OpenJDK with bug-fixes what might be an option. -Anyhow, as you want to have your development environment close to production, the productively used JDK (most likely OracleJDK) should be preferred also for development. +However, there is https://adoptium.net/[Adoptium] that provides forked releases of OpenJDK with bug-fixes what might be an option. + +The easiest way to get all this setup for developers is using https://github.com/devonfw/ide[devonfw-ide]. + +== Garbage Collection + +A key feature of Java is automatic garbage collection (GC). +Over time different garbage collectors have been implemented within the JVM. +The good news is that usually you do not have to care about all this. +However, at some point you might get an `OutOfMemoryError` or other effects related to GC and heap issues. +Therefore, we strongly recommend you to do continous https://www.baeldung.com/java-gc-logging-to-file[logging of your GC activity] in your environments up to production. +These GC logging does not cause relevant overhead so it can be enabled 7x24. +Whenever you might have heap issues or a memory leak, you can simply analyze these GC logs. +Simply transfer the logs from the environment server to your local machine. +As the GC logs do not contain data that is sensitive to your app (regarding GPDR, customer data, etc.) this should be relatively easy to arrange. +To analyze these GC logs, we recommend https://github.com/chewiebug/GCViewer[GCViewer]. +If you are already using https://github.com/devonfw/ide[devonfw-ide], that integrates all cool developer tools you may need, you can just call this command: +``` +devon gcviewer +``` +In the UI of GCViewer, simply open your GC logfile and you will get a visualization of the heap activity over time. + +== Thread Dump + +Sometimes you may face concurrency issues or even deadlocks where threads block each other. +In such case you should https://www.baeldung.com/java-thread-dump[create a thread-dump]. +We even recommend you to create a series of e.g. 3-5 thread-dumps with a short delay of e.g. a minute bettwen each of them. +This will help you to trace down problems of waiting or blocked threads. == Upgrading From 15925ea73f570b2fa4135d0d73ee162aa22b887e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Hohwiller?= Date: Mon, 12 Sep 2022 17:50:14 +0200 Subject: [PATCH 06/10] Update guide-jdk.asciidoc --- documentation/guide-jdk.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/guide-jdk.asciidoc b/documentation/guide-jdk.asciidoc index 81fc21e2..d78e0fb1 100644 --- a/documentation/guide-jdk.asciidoc +++ b/documentation/guide-jdk.asciidoc @@ -42,6 +42,7 @@ If you are already using https://github.com/devonfw/ide[devonfw-ide], that integ devon gcviewer ``` In the UI of GCViewer, simply open your GC logfile and you will get a visualization of the heap activity over time. +For more details see https://sematext.com/blog/java-garbage-collection-logs/[here]. == Thread Dump From bfc23e0e13e3be2877e6a1558530fbb8dab494e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Hohwiller?= Date: Mon, 12 Sep 2022 17:52:43 +0200 Subject: [PATCH 07/10] Update guide-jdk.asciidoc --- documentation/guide-jdk.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/guide-jdk.asciidoc b/documentation/guide-jdk.asciidoc index d78e0fb1..139d025f 100644 --- a/documentation/guide-jdk.asciidoc +++ b/documentation/guide-jdk.asciidoc @@ -31,6 +31,7 @@ A key feature of Java is automatic garbage collection (GC). Over time different garbage collectors have been implemented within the JVM. The good news is that usually you do not have to care about all this. However, at some point you might get an `OutOfMemoryError` or other effects related to GC and heap issues. +You should also be aware that when a lot of heap is consumed, a full GC may pause the JVM for some time causing other issues like performance problems or even connection timeouts. Therefore, we strongly recommend you to do continous https://www.baeldung.com/java-gc-logging-to-file[logging of your GC activity] in your environments up to production. These GC logging does not cause relevant overhead so it can be enabled 7x24. Whenever you might have heap issues or a memory leak, you can simply analyze these GC logs. From ecc1e81b6f9c95178f0068564b1d475f4b4b42a6 Mon Sep 17 00:00:00 2001 From: abhaychandel-capgemini <79638442+abhaychandel-capgemini@users.noreply.github.com> Date: Fri, 16 Sep 2022 10:03:58 +0530 Subject: [PATCH 08/10] Added stale bot (#574) --- .github/stale.yml | 59 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 .github/stale.yml diff --git a/.github/stale.yml b/.github/stale.yml new file mode 100644 index 00000000..ff2e410e --- /dev/null +++ b/.github/stale.yml @@ -0,0 +1,59 @@ +# Configuration for probot-stale - https://github.com/probot/stale + +# Number of days of inactivity before an Issue or Pull Request becomes stale +daysUntilStale: 30 + +# Number of days of inactivity before an Issue or Pull Request with the stale label is closed. +# Set to false to disable. If disabled, issues still need to be closed manually, but will remain marked as stale. +daysUntilClose: 7 + +# Only issues or pull requests with all of these labels are check if stale. Defaults to `[]` (disabled) +onlyLabels: [] + +# Issues or Pull Requests with these labels will never be considered stale. Set to `[]` to disable +exemptLabels: + - dependencies + +# Set to true to ignore issues in a project (defaults to false) +exemptProjects: false + +# Set to true to ignore issues in a milestone (defaults to false) +exemptMilestones: false + +# Set to true to ignore issues with an assignee (defaults to false) +exemptAssignees: false + +# Label to use when marking as stale +staleLabel: wontfix + +# Comment to post when marking as stale. Set to `false` to disable +markComment: > + This issue has been automatically marked as stale because it has not had + recent activity. It will be closed if no further activity occurs. Thank you + for your contributions. + +# Comment to post when removing the stale label. +# unmarkComment: > +# Your comment here. + +# Comment to post when closing a stale Issue or Pull Request. +# closeComment: > +# Your comment here. + +# Limit the number of actions per hour, from 1-30. Default is 30 +limitPerRun: 30 + +# Limit to only `issues` or `pulls` +# only: issues + +# Optionally, specify configuration settings that are specific to just 'issues' or 'pulls': +# pulls: +# daysUntilStale: 30 +# markComment: > +# This pull request has been automatically marked as stale because it has not had +# recent activity. It will be closed if no further activity occurs. Thank you +# for your contributions. + +# issues: +# exemptLabels: +# - confirmed From b6e54ab5df028bd17a15a76ee72ac7dfeb179a48 Mon Sep 17 00:00:00 2001 From: denise-khuu <74537227+denise-khuu@users.noreply.github.com> Date: Fri, 18 Nov 2022 06:37:40 +0100 Subject: [PATCH 09/10] Feature/new page announcement (#577) * bugfix syntax error # -> = * added warning --- documentation/12-factor-app-devon4j.asciidoc | 4 ++++ documentation/Home.asciidoc | 4 ++++ .../Spring-native-vs-Quarkus.asciidoc | 4 ++++ .../alternative-microservice-netflix.asciidoc | 4 ++++ documentation/architecture.asciidoc | 4 ++++ .../build-release-run-12factor.asciidoc | 4 ++++ documentation/coding-conventions.asciidoc | 4 ++++ documentation/coding-tools.asciidoc | 4 ++++ ...cision-between-Spring-and-Quarkus.asciidoc | 4 ++++ .../decision-service-framework.asciidoc | 4 ++++ documentation/devon4j-doc.asciidoc | 7 +++++- documentation/devon4j.asciidoc | 4 ++++ .../guide-access-control-schema.asciidoc | 4 ++++ documentation/guide-access-control.asciidoc | 4 ++++ documentation/guide-accessibility.asciidoc | 4 ++++ documentation/guide-aop.asciidoc | 4 ++++ documentation/guide-api-first.asciidoc | 4 ++++ documentation/guide-apm.asciidoc | 4 ++++ documentation/guide-auditing.asciidoc | 4 ++++ documentation/guide-batch-layer.asciidoc | 4 ++++ documentation/guide-beanmapping.asciidoc | 6 +++++ documentation/guide-blob-support.asciidoc | 6 +++++ documentation/guide-caching.asciidoc | 4 ++++ documentation/guide-client-layer.asciidoc | 4 ++++ documentation/guide-common.asciidoc | 4 ++++ documentation/guide-component-facade.asciidoc | 4 ++++ documentation/guide-component.asciidoc | 4 ++++ .../guide-configuration-mapping.asciidoc | 4 ++++ documentation/guide-configuration.asciidoc | 4 ++++ documentation/guide-cors-support.asciidoc | 4 ++++ documentation/guide-csrf.asciidoc | 4 ++++ documentation/guide-dao.asciidoc | 4 ++++ documentation/guide-data-permission.asciidoc | 4 ++++ documentation/guide-dataaccess-layer.asciidoc | 4 ++++ .../guide-database-migration.asciidoc | 4 ++++ documentation/guide-datatype.asciidoc | 4 ++++ .../guide-dependency-injection.asciidoc | 4 ++++ documentation/guide-domain-layer.asciidoc | 4 ++++ documentation/guide-dto.asciidoc | 6 +++++ documentation/guide-eto-cto.asciidoc | 6 +++++ documentation/guide-exceptions.asciidoc | 4 ++++ documentation/guide-feature-toggle.asciidoc | 4 ++++ documentation/guide-flyway.asciidoc | 4 ++++ documentation/guide-i18n.asciidoc | 6 +++++ documentation/guide-jdk.asciidoc | 4 ++++ documentation/guide-jee.asciidoc | 4 ++++ documentation/guide-jms.asciidoc | 4 ++++ documentation/guide-jmx.asciidoc | 4 ++++ documentation/guide-jpa-idref.asciidoc | 4 ++++ documentation/guide-jpa-performance.asciidoc | 4 ++++ documentation/guide-jpa-query.asciidoc | 4 ++++ documentation/guide-jpa.asciidoc | 4 ++++ documentation/guide-json.asciidoc | 4 ++++ documentation/guide-jwt.asciidoc | 4 ++++ documentation/guide-kafka.asciidoc | 4 ++++ documentation/guide-liquibase.asciidoc | 4 ++++ documentation/guide-log-monitoring.asciidoc | 4 ++++ documentation/guide-logging.asciidoc | 4 ++++ documentation/guide-logic-layer.asciidoc | 4 ++++ documentation/guide-lombok.asciidoc | 4 ++++ documentation/guide-microservice.asciidoc | 4 ++++ ...guide-migration-oasp3-to-devon3.1.asciidoc | 24 +++++++++++-------- .../guide-migration-spring-quarkus.asciidoc | 4 ++++ documentation/guide-monitoring.asciidoc | 4 ++++ documentation/guide-openapi.asciidoc | 4 ++++ documentation/guide-queueing.asciidoc | 4 ++++ documentation/guide-repository.asciidoc | 4 ++++ documentation/guide-rest-philosophy.asciidoc | 4 ++++ documentation/guide-rest.asciidoc | 4 ++++ documentation/guide-scm.asciidoc | 4 ++++ documentation/guide-security.asciidoc | 4 ++++ documentation/guide-service-client.asciidoc | 4 ++++ documentation/guide-service-layer.asciidoc | 4 ++++ .../guide-service-versioning.asciidoc | 4 ++++ documentation/guide-soap.asciidoc | 4 ++++ documentation/guide-sql.asciidoc | 4 ++++ .../guide-structure-classic.asciidoc | 4 ++++ documentation/guide-structure-modern.asciidoc | 4 ++++ documentation/guide-structure.asciidoc | 4 ++++ .../guide-testing-snapshots.asciidoc | 4 ++++ documentation/guide-testing.asciidoc | 4 ++++ documentation/guide-text-search.asciidoc | 4 ++++ documentation/guide-transactions.asciidoc | 4 ++++ documentation/guide-transferobject.asciidoc | 6 +++++ documentation/guide-usecase.asciidoc | 4 ++++ documentation/guide-validation.asciidoc | 4 ++++ documentation/guide-xml.asciidoc | 4 ++++ ...rmance-comparision-spring-quarkus.asciidoc | 4 ++++ documentation/quarkus.asciidoc | 4 ++++ ...ing-started-for-spring-developers.asciidoc | 4 ++++ .../quarkus/getting-started-quarkus.asciidoc | 4 ++++ .../guide-authentication-quarkus.asciidoc | 4 ++++ .../guide-beanmapping-quarkus.asciidoc | 4 ++++ .../quarkus/guide-exception-handling.asciidoc | 4 ++++ .../quarkus/guide-native-image.asciidoc | 4 ++++ .../guide-quarkus-configuration.asciidoc | 4 ++++ .../quarkus/guide-quarkus-testing.asciidoc | 4 ++++ .../quarkus/quarkus-template.asciidoc | 4 ++++ documentation/spring.asciidoc | 4 ++++ .../guide-authentication-spring.asciidoc | 4 ++++ .../spring/guide-beanmapping-spring.asciidoc | 6 +++++ .../spring/guide-cors-spring.asciidoc | 4 ++++ .../guide-devon4j-spring-repository.asciidoc | 4 ++++ .../spring/guide-jwt-spring.asciidoc | 4 ++++ .../spring/guide-kafka-spring.asciidoc | 4 ++++ .../spring/guide-querydsl-spring.asciidoc | 4 ++++ .../guide-service-client-spring.asciidoc | 4 ++++ .../guide-spring-configuration.asciidoc | 4 ++++ .../spring/guide-spring-testing.asciidoc | 4 ++++ documentation/tutorial-newapp.asciidoc | 4 ++++ 110 files changed, 466 insertions(+), 11 deletions(-) diff --git a/documentation/12-factor-app-devon4j.asciidoc b/documentation/12-factor-app-devon4j.asciidoc index 77e793bd..0242449e 100644 --- a/documentation/12-factor-app-devon4j.asciidoc +++ b/documentation/12-factor-app-devon4j.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = 12-factor-app with devon4j This document mainly focuses on discussing how can you create 12 factor app with devon4j. To know more about this 12 factors you can refer https://12factor.net/[here] . Twelve factor is mainly focus on creating cloud native applications. These are the guidelines on what factors you need to consider in different stages of application lifecycle. diff --git a/documentation/Home.asciidoc b/documentation/Home.asciidoc index 3c20c6bc..d0dd4393 100644 --- a/documentation/Home.asciidoc +++ b/documentation/Home.asciidoc @@ -1,3 +1,7 @@ +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = devonfw for Java (devon4j) Welcome to the Java edition of devonfw. devon4j is documented by a platform guide (see the side-bar of this wiki) to be used in your projects. diff --git a/documentation/Spring-native-vs-Quarkus.asciidoc b/documentation/Spring-native-vs-Quarkus.asciidoc index f26df0f6..2f0af01f 100644 --- a/documentation/Spring-native-vs-Quarkus.asciidoc +++ b/documentation/Spring-native-vs-Quarkus.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Spring Native vs Quarkus Nowadays, it is very common to write an application and deploy it to a cloud. diff --git a/documentation/alternative-microservice-netflix.asciidoc b/documentation/alternative-microservice-netflix.asciidoc index 383c550e..6126604c 100644 --- a/documentation/alternative-microservice-netflix.asciidoc +++ b/documentation/alternative-microservice-netflix.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + == Microservices based on Netflix-Tools Devonfw microservices approach is based on http://cloud.spring.io/spring-cloud-netflix/[Spring Cloud Netflix], that provides all the main components for microservices integrated within Spring Boot context. diff --git a/documentation/architecture.asciidoc b/documentation/architecture.asciidoc index 7f7cbc7a..9492697d 100644 --- a/documentation/architecture.asciidoc +++ b/documentation/architecture.asciidoc @@ -3,6 +3,10 @@ toc::[] :idprefix: :idseparator: - +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Architecture There are many different views that are summarized by the term _architecture_. First, we will introduce the xref:key-principles[key principles] and xref:architecture-principles[architecture principles] of devonfw. Then, we will go into details of the the xref:application-architecture[architecture of an application]. diff --git a/documentation/build-release-run-12factor.asciidoc b/documentation/build-release-run-12factor.asciidoc index 7662697d..1c6eb9d0 100644 --- a/documentation/build-release-run-12factor.asciidoc +++ b/documentation/build-release-run-12factor.asciidoc @@ -1,3 +1,7 @@ +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Build, release and run *Strictly separate build and run stages* diff --git a/documentation/coding-conventions.asciidoc b/documentation/coding-conventions.asciidoc index 8c948ef9..f56efcdd 100644 --- a/documentation/coding-conventions.asciidoc +++ b/documentation/coding-conventions.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Coding Conventions The code should follow general conventions for Java (see http://www.oracle.com/technetwork/java/namingconventions-139351.html[Oracle Naming Conventions], https://google.github.io/styleguide/javaguide.html[Google Java Style], etc.).We consider this as common sense and provide configurations for http://www.sonarqube.org/[SonarQube] and related tools such as http://checkstyle.sourceforge.net/[Checkstyle] instead of repeating this here. diff --git a/documentation/coding-tools.asciidoc b/documentation/coding-tools.asciidoc index 3ee2634f..56a0ae3f 100644 --- a/documentation/coding-tools.asciidoc +++ b/documentation/coding-tools.asciidoc @@ -1,6 +1,10 @@ :toc: toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Tools .Development Tools used for devon4j diff --git a/documentation/decision-between-Spring-and-Quarkus.asciidoc b/documentation/decision-between-Spring-and-Quarkus.asciidoc index 6bb3f50f..ae128e62 100644 --- a/documentation/decision-between-Spring-and-Quarkus.asciidoc +++ b/documentation/decision-between-Spring-and-Quarkus.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Decision between Spring and Quarkus == Spring diff --git a/documentation/decision-service-framework.asciidoc b/documentation/decision-service-framework.asciidoc index f65499aa..d3a294d1 100644 --- a/documentation/decision-service-framework.asciidoc +++ b/documentation/decision-service-framework.asciidoc @@ -1,6 +1,10 @@ :toc: toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Decision Sheet for Choosing a Service Framework We need to choose which framework(s) we want to use for building services. For the devonfw, we focus on a standard API, if available. However, we also want to recommend an implementation. While projects would still be able to choose whatever they want, we want to suggest the best, most robust, and established solution. This way, projects do not have to worry about the decision and can rely on a production-ready framework without running into any trouble. Also, besides the standard, the configuration of the implementation framework differs, so we want to give instructions in the documentation and by our sample application. This is why, in the end, the implementation also matters. If a project has a customer demand to use something else, the project has to take care of it. We will always suggest and "support" ONE solution. diff --git a/documentation/devon4j-doc.asciidoc b/documentation/devon4j-doc.asciidoc index 103bad56..b25f028e 100644 --- a/documentation/devon4j-doc.asciidoc +++ b/documentation/devon4j-doc.asciidoc @@ -1 +1,6 @@ -include::devon4j.asciidoc[] \ No newline at end of file +include::devon4j.asciidoc[] + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + diff --git a/documentation/devon4j.asciidoc b/documentation/devon4j.asciidoc index 8945c5d2..1c664e94 100644 --- a/documentation/devon4j.asciidoc +++ b/documentation/devon4j.asciidoc @@ -1,3 +1,7 @@ +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Java :description: comprehensive documentation for the Java stack of devonfw. diff --git a/documentation/guide-access-control-schema.asciidoc b/documentation/guide-access-control-schema.asciidoc index 198259b6..88db3757 100644 --- a/documentation/guide-access-control-schema.asciidoc +++ b/documentation/guide-access-control-schema.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Access Control Schema With release `3.0.0` the `access-control-schema.xml` has been deprecated. You may still use it and find the documentation in this section. However, for new devonfw applications always start with the new approach described in link:guide-access-control#access-control-config.asciidoc[access control config]. diff --git a/documentation/guide-access-control.asciidoc b/documentation/guide-access-control.asciidoc index 7b2fefad..06ef47ae 100644 --- a/documentation/guide-access-control.asciidoc +++ b/documentation/guide-access-control.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Access-Control Access-Control is a central and important aspect of link:guide-security.asciidoc[Security]. It consists of two major aspects: diff --git a/documentation/guide-accessibility.asciidoc b/documentation/guide-accessibility.asciidoc index 8b520341..f34dd331 100644 --- a/documentation/guide-accessibility.asciidoc +++ b/documentation/guide-accessibility.asciidoc @@ -1,6 +1,10 @@ :toc: toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Accessibility TODO diff --git a/documentation/guide-aop.asciidoc b/documentation/guide-aop.asciidoc index c797b8e8..e977eb3e 100644 --- a/documentation/guide-aop.asciidoc +++ b/documentation/guide-aop.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Aspect Oriented Programming (AOP) http://en.wikipedia.org/wiki/Aspect-oriented_programming[AOP] is a powerful feature for cross-cutting concerns. However, if used extensive and for the wrong things an application can get unmaintainable. Therefore we give you the best practices where and how to use AOP properly. diff --git a/documentation/guide-api-first.asciidoc b/documentation/guide-api-first.asciidoc index 0b324b4d..d1cfef95 100644 --- a/documentation/guide-api-first.asciidoc +++ b/documentation/guide-api-first.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = API first development guide Cloud native promotes the use of microservices, which are loosely coupled and self-contained. These services communicate with each other using a well-defined interface or API, and no consumer needs to be aware of any implementation details of the provider. There could even be multiple providers of the same API, or we can decide to swap existing implementation for a new one, without disrupting our clients - all because we adhere to a well defined API. diff --git a/documentation/guide-apm.asciidoc b/documentation/guide-apm.asciidoc index 1b85507a..074358bb 100644 --- a/documentation/guide-apm.asciidoc +++ b/documentation/guide-apm.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Application Performance Management This guide gives hints how to manage, monitor and analyse performance of Java applications. diff --git a/documentation/guide-auditing.asciidoc b/documentation/guide-auditing.asciidoc index 0d7b8536..3ea00a5a 100644 --- a/documentation/guide-auditing.asciidoc +++ b/documentation/guide-auditing.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Auditing For database auditing we use http://envers.jboss.org/[hibernate envers]. If you want to use auditing ensure you have the following dependency in your +pom.xml+: diff --git a/documentation/guide-batch-layer.asciidoc b/documentation/guide-batch-layer.asciidoc index 057892fe..311cd561 100644 --- a/documentation/guide-batch-layer.asciidoc +++ b/documentation/guide-batch-layer.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Batch Layer We understand batch processing as a bulk-oriented, non-interactive, typically long running execution of tasks. For simplicity, we use the term "batch" or "batch job" for such tasks in the following documentation. diff --git a/documentation/guide-beanmapping.asciidoc b/documentation/guide-beanmapping.asciidoc index be2905bb..91ac1a9d 100644 --- a/documentation/guide-beanmapping.asciidoc +++ b/documentation/guide-beanmapping.asciidoc @@ -1,6 +1,12 @@ :toc: macro toc::[] //Replaced old person examples with new User example + + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Bean-Mapping For decoupling, you sometimes need to create separate objects (beans) for a different view. E.g. for an external service, you will use a link:guide-transferobject.asciidoc[transfer-object] instead of the link:guide-jpa.asciidoc#entity[persistence entity] so internal changes to the entity do not implicitly change or break the service. diff --git a/documentation/guide-blob-support.asciidoc b/documentation/guide-blob-support.asciidoc index 393144df..95ca4200 100644 --- a/documentation/guide-blob-support.asciidoc +++ b/documentation/guide-blob-support.asciidoc @@ -1,5 +1,11 @@ :toc: macro toc::[] + + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = BLOB support BLOB stands for **B**inary **L**arge **Ob**ject. A BLOB may be an image, an office document, ZIP archive or any other multimedia object. diff --git a/documentation/guide-caching.asciidoc b/documentation/guide-caching.asciidoc index 76a01a5b..de1b1d2e 100644 --- a/documentation/guide-caching.asciidoc +++ b/documentation/guide-caching.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Caching //Maybe finish the guide? Caching is a technical approach to improve performance. While it may appear easy on the first sight it is an advanced topic. In general, try to use caching only when required for performance reasons. If you come to the point that you need caching first think about: diff --git a/documentation/guide-client-layer.asciidoc b/documentation/guide-client-layer.asciidoc index fe451b43..b453d64d 100644 --- a/documentation/guide-client-layer.asciidoc +++ b/documentation/guide-client-layer.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Client Layer There are various technical approaches to building GUI clients. The devonfw proposes rich clients that connect to the server via data-oriented services (e.g. using REST with JSON). diff --git a/documentation/guide-common.asciidoc b/documentation/guide-common.asciidoc index a4f7711b..9c0f70b6 100644 --- a/documentation/guide-common.asciidoc +++ b/documentation/guide-common.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Common In our link:coding-conventions.asciidoc[coding-conventions] we define a clear link:coding-conventions.asciidoc#packages[packaging] and link:coding-conventions.asciidoc#layers[layering]. diff --git a/documentation/guide-component-facade.asciidoc b/documentation/guide-component-facade.asciidoc index 53d04e21..959c73fa 100644 --- a/documentation/guide-component-facade.asciidoc +++ b/documentation/guide-component-facade.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Component Facade [NOTE] Our recommended approach for implementing the logic layer is link:guide-usecase.asciidoc[use-cases] diff --git a/documentation/guide-component.asciidoc b/documentation/guide-component.asciidoc index 9708dc25..9454463d 100644 --- a/documentation/guide-component.asciidoc +++ b/documentation/guide-component.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Components Following link:architecture.asciidoc#architecture-principles[separation-of-concerns] we divide an application into components using our link:coding-conventions.asciidoc#packages[package-conventions] and link:guide-structure.asciidoc[project structure]. diff --git a/documentation/guide-configuration-mapping.asciidoc b/documentation/guide-configuration-mapping.asciidoc index 131dadae..2d590215 100644 --- a/documentation/guide-configuration-mapping.asciidoc +++ b/documentation/guide-configuration-mapping.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Mapping configuration to your code If you are using `spring-boot` as suggested by `devon4j` your application can be configured by `application.properties` file as described in link:guide-configuration.asciidoc[configuration]. diff --git a/documentation/guide-configuration.asciidoc b/documentation/guide-configuration.asciidoc index 9f31e0c1..cb3cb3d7 100644 --- a/documentation/guide-configuration.asciidoc +++ b/documentation/guide-configuration.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Configuration An application needs to be configurable in order to allow internal setup (like CDI) but also to allow externalized configuration of a deployed package (e.g. integration into runtime environment). We rely on a comprehensive configuration approach following a "convention over configuration" pattern. This guide adds on to this by detailed instructions and best-practices how to deal with configurations. diff --git a/documentation/guide-cors-support.asciidoc b/documentation/guide-cors-support.asciidoc index 4cdfd952..e1fb2ef0 100644 --- a/documentation/guide-cors-support.asciidoc +++ b/documentation/guide-cors-support.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = CORS support When you are developing Javascript client and server application separately, you have to deal with cross domain issues. We have to request from a origin domain distinct to target domain and browser does not allow this. diff --git a/documentation/guide-csrf.asciidoc b/documentation/guide-csrf.asciidoc index d2ce4e44..8a4f1c6e 100644 --- a/documentation/guide-csrf.asciidoc +++ b/documentation/guide-csrf.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Cross-site request forgery (CSRF) CSRF is a type of malicious exploit of a web application that allows an attacker to induce users to perform actions that they do not intend to perform. diff --git a/documentation/guide-dao.asciidoc b/documentation/guide-dao.asciidoc index 3b459dee..e4cfc995 100644 --- a/documentation/guide-dao.asciidoc +++ b/documentation/guide-dao.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Data Access Object The _Data Access Objects_ (DAOs) are part of the persistence layer. diff --git a/documentation/guide-data-permission.asciidoc b/documentation/guide-data-permission.asciidoc index dae4a07b..bb4691de 100644 --- a/documentation/guide-data-permission.asciidoc +++ b/documentation/guide-data-permission.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Data-permissions In some projects there are demands for permissions and authorization that is dependent on the processed data. E.g. a user may only be allowed to read or write data for a specific region. This is adding some additional complexity to your authorization. If you can avoid this it is always best to keep things simple. However, in various cases this is a requirement. Therefore the following sections give you guidance and patterns how to solve this properly. diff --git a/documentation/guide-dataaccess-layer.asciidoc b/documentation/guide-dataaccess-layer.asciidoc index 7bb158e1..1268eaf4 100644 --- a/documentation/guide-dataaccess-layer.asciidoc +++ b/documentation/guide-dataaccess-layer.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Data-Access Layer The data-access layer is responsible for all outgoing connections to access and process data. This is mainly about accessing data from a persistent data-store. External system could also be accessed from the data-access layer if they match this definition, e.g. a mongo-db via rest services. diff --git a/documentation/guide-database-migration.asciidoc b/documentation/guide-database-migration.asciidoc index d93a6c48..7c022f2f 100644 --- a/documentation/guide-database-migration.asciidoc +++ b/documentation/guide-database-migration.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Database Migration When you have a schema-based https://github.com/devonfw/devonfw-guide/blob/master/general/db/guide-database.asciidoc[database], diff --git a/documentation/guide-datatype.asciidoc b/documentation/guide-datatype.asciidoc index b64afa36..001aae57 100644 --- a/documentation/guide-datatype.asciidoc +++ b/documentation/guide-datatype.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Datatypes [quote, mmm project, datatype javadoc] diff --git a/documentation/guide-dependency-injection.asciidoc b/documentation/guide-dependency-injection.asciidoc index e5ade8f1..21cf93fd 100644 --- a/documentation/guide-dependency-injection.asciidoc +++ b/documentation/guide-dependency-injection.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Dependency Injection Dependency injection is one of the most important design patterns and is a key principle to a modular and component based architecture. The Java Standard for dependency injection is http://docs.oracle.com/javaee/6/api/javax/inject/package-summary.html[javax.inject (JSR330)] that we use in combination with http://docs.oracle.com/javaee/5/api/javax/annotation/package-summary.html[JSR250]. diff --git a/documentation/guide-domain-layer.asciidoc b/documentation/guide-domain-layer.asciidoc index a6a9142e..f797e065 100644 --- a/documentation/guide-domain-layer.asciidoc +++ b/documentation/guide-domain-layer.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Domain Layer The domain layer is responsible for the data-model and mapping it to a https://github.com/devonfw/devonfw-guide/blob/master/general/db/guide-database.asciidoc[database]. diff --git a/documentation/guide-dto.asciidoc b/documentation/guide-dto.asciidoc index 11e9f576..febd9520 100644 --- a/documentation/guide-dto.asciidoc +++ b/documentation/guide-dto.asciidoc @@ -1,5 +1,11 @@ :toc: macro toc::[] + + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = DTO approach As described in link:guide-structure-modern.asciidoc[our modern structure guide], for application e.g. with microservices architecture where we build smaller applications compared to monoliths, we recommend keeping things as simple as possible. The same principle applies to transfer object. Instead of using different types of transfer objects for each entity such as link:guide-eto-cto.asciidoc[ETO and CTO], we highly suggest using one _data transfer object_ (DTO) named `«BusinessObject»Dto`. diff --git a/documentation/guide-eto-cto.asciidoc b/documentation/guide-eto-cto.asciidoc index aa05ef7f..e8e8afef 100644 --- a/documentation/guide-eto-cto.asciidoc +++ b/documentation/guide-eto-cto.asciidoc @@ -1,5 +1,11 @@ :toc: macro toc::[] + + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = ETO and CTO approach == ETO diff --git a/documentation/guide-exceptions.asciidoc b/documentation/guide-exceptions.asciidoc index 7fa53954..2a535477 100644 --- a/documentation/guide-exceptions.asciidoc +++ b/documentation/guide-exceptions.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Exception Handling diff --git a/documentation/guide-feature-toggle.asciidoc b/documentation/guide-feature-toggle.asciidoc index 40fded8f..1e800f65 100644 --- a/documentation/guide-feature-toggle.asciidoc +++ b/documentation/guide-feature-toggle.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Feature-Toggles The most software developing teams use Feature-Branching to be able to work in parallel and maintain a stable main branch in the VCS. However Feature-Branching might not be the ideal tool in every case because of big merges and isolation between development groups. In many cases, Feature-Toggles can avoid some of these problems, so these should definitely be considered to be used in the collaborative software development. diff --git a/documentation/guide-flyway.asciidoc b/documentation/guide-flyway.asciidoc index 70058681..043f4e9f 100644 --- a/documentation/guide-flyway.asciidoc +++ b/documentation/guide-flyway.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Flyway http://flywaydb.org/[Flyway] is a tool for link:guide-database-migration.asciidoc[database migration and schema versioning]. diff --git a/documentation/guide-i18n.asciidoc b/documentation/guide-i18n.asciidoc index 13fa7d22..6785576b 100644 --- a/documentation/guide-i18n.asciidoc +++ b/documentation/guide-i18n.asciidoc @@ -1,5 +1,11 @@ :toc: macro toc::[] + + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Internationalization //The property file doesn't exist anymore but the example looks fine. Keep it? Internationalization (I18N) is about writing code independent from locale-specific information. diff --git a/documentation/guide-jdk.asciidoc b/documentation/guide-jdk.asciidoc index 139d025f..bed0ccab 100644 --- a/documentation/guide-jdk.asciidoc +++ b/documentation/guide-jdk.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Java Development Kit The https://en.wikipedia.org/wiki/Java_Development_Kit[Java Development Kit] is an implementation of the Java platform. It provides the https://en.wikipedia.org/wiki/Java_virtual_machine[Java Virtual Machine] (JVM) and the Java Runtime Environment (JRE). diff --git a/documentation/guide-jee.asciidoc b/documentation/guide-jee.asciidoc index c7696d63..03b62c6e 100644 --- a/documentation/guide-jee.asciidoc +++ b/documentation/guide-jee.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = JEE This section is about Java Enterprise Edition (JEE). diff --git a/documentation/guide-jms.asciidoc b/documentation/guide-jms.asciidoc index 77f64891..dbb15f84 100644 --- a/documentation/guide-jms.asciidoc +++ b/documentation/guide-jms.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Messaging Messaging in Java is done using the https://en.wikipedia.org/wiki/Java_Message_Service[JMS] standard from JEE. diff --git a/documentation/guide-jmx.asciidoc b/documentation/guide-jmx.asciidoc index e23332a9..702432cf 100644 --- a/documentation/guide-jmx.asciidoc +++ b/documentation/guide-jmx.asciidoc @@ -1,6 +1,10 @@ :toc: toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = JMX https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html[JMX] (Java Management Extensions) is the official Java link:guide-monitoring.asciidoc[monitoring] solution. diff --git a/documentation/guide-jpa-idref.asciidoc b/documentation/guide-jpa-idref.asciidoc index f6c8b5e9..b72d7664 100644 --- a/documentation/guide-jpa-idref.asciidoc +++ b/documentation/guide-jpa-idref.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = IdRef IdRef can be used to reference other entities in TOs in order to make them type-safe and semantically more expressive. diff --git a/documentation/guide-jpa-performance.asciidoc b/documentation/guide-jpa-performance.asciidoc index e0289e88..21bba5a7 100644 --- a/documentation/guide-jpa-performance.asciidoc +++ b/documentation/guide-jpa-performance.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = JPA Performance When using JPA the developer sometimes does not see or understand where and when statements to the database are triggered. [quote, Dan Allen, https://epdf.tips/seam-in-action.html] diff --git a/documentation/guide-jpa-query.asciidoc b/documentation/guide-jpa-query.asciidoc index c617467b..8832d30f 100644 --- a/documentation/guide-jpa-query.asciidoc +++ b/documentation/guide-jpa-query.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Queries The http://www.oracle.com/technetwork/java/javaee/tech/persistence-jsp-140049.html[Java Persistence API (JPA)] defines its own query language, the https://docs.oracle.com/html/E13946_01/ejb3_langref.html[_java persistence query language_ (JPQL)] (see also https://docs.oracle.com/javaee/7/tutorial/persistence-querylanguage.htm[JPQL tutorial]), which is similar to SQL but operates on entities and their attributes instead of tables and columns. diff --git a/documentation/guide-jpa.asciidoc b/documentation/guide-jpa.asciidoc index 8c78e93d..d4ecfce7 100644 --- a/documentation/guide-jpa.asciidoc +++ b/documentation/guide-jpa.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Java Persistence API For mapping java objects to a relational database we use the http://www.oracle.com/technetwork/java/javaee/tech/persistence-jsp-140049.html[Java Persistence API (JPA)]. diff --git a/documentation/guide-json.asciidoc b/documentation/guide-json.asciidoc index 82022bca..e844aac8 100644 --- a/documentation/guide-json.asciidoc +++ b/documentation/guide-json.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = JSON http://en.wikipedia.org/wiki/JSON[JSON] (JavaScript Object Notation) is a popular format to represent and exchange data especially for modern web-clients. For mapping Java objects to JSON and vice-versa there is no official standard API. We use the established and powerful open-source solution http://wiki.fasterxml.com/JacksonHome[Jackson]. diff --git a/documentation/guide-jwt.asciidoc b/documentation/guide-jwt.asciidoc index d946fc14..47f25b7d 100644 --- a/documentation/guide-jwt.asciidoc +++ b/documentation/guide-jwt.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = JWT https://jwt.io[JWT] (JSON Web Token) is an open standard (see https://tools.ietf.org/html/rfc7519[RFC 7519]) for creating link:guide-json.asciidoc[JSON] based access tokens that assert some number of claims. diff --git a/documentation/guide-kafka.asciidoc b/documentation/guide-kafka.asciidoc index 0443caf7..f82c127c 100644 --- a/documentation/guide-kafka.asciidoc +++ b/documentation/guide-kafka.asciidoc @@ -3,6 +3,10 @@ toc::[] WARNING: devon4j-kafka has been abandoned. Its main feature was the implementation of a retry pattern using multiple topics. This implementation has become an integral part of Spring Kafka. We recommend to use Spring Kafkas own implemenation for retries. +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Messaging Services Messaging Services provide an asynchronous communication mechanism between applications. Technically this is implemented using http://kafka.apache.org/documentation.html[Apache Kafka] . diff --git a/documentation/guide-liquibase.asciidoc b/documentation/guide-liquibase.asciidoc index 4de630cc..11e9289c 100644 --- a/documentation/guide-liquibase.asciidoc +++ b/documentation/guide-liquibase.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Liquibase https://www.liquibase.org/[Liquibase] is a tool for link:guide-database-migration.asciidoc[database migration and schema versioning]. diff --git a/documentation/guide-log-monitoring.asciidoc b/documentation/guide-log-monitoring.asciidoc index 0bff4ac7..79b192cd 100644 --- a/documentation/guide-log-monitoring.asciidoc +++ b/documentation/guide-log-monitoring.asciidoc @@ -1,6 +1,10 @@ :toc: toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Log-Monitoring Log-monitoring is an aspect of link:guide-monitoring.asciidoc[monitoring] with a strict focus on link:guide-logging.asciidoc[logging]. diff --git a/documentation/guide-logging.asciidoc b/documentation/guide-logging.asciidoc index 199a0592..f8ee24a1 100644 --- a/documentation/guide-logging.asciidoc +++ b/documentation/guide-logging.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Logging We recommend to use http://www.slf4j.org/[SLF4J] as API for logging, that has become a de facto standard in Java as it has a much better design than `java.util.logging` offered by the JDK. diff --git a/documentation/guide-logic-layer.asciidoc b/documentation/guide-logic-layer.asciidoc index 3f05c1a3..ca51f0b8 100644 --- a/documentation/guide-logic-layer.asciidoc +++ b/documentation/guide-logic-layer.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Logic Layer The logic layer is the heart of the application and contains the main business logic. diff --git a/documentation/guide-lombok.asciidoc b/documentation/guide-lombok.asciidoc index 79997b14..4e39861a 100644 --- a/documentation/guide-lombok.asciidoc +++ b/documentation/guide-lombok.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Lombok https://projectlombok.org/[Lombok] is a library that works with an annotation processor and will generate code for you to save you some time and reduce the amount of boilerplate code in your project. Lombok can generate getter and setter, equals methods, automate your logging variables for your classes, and more. Follow the https://projectlombok.org/features/all[list of all the features] provided by Lombok to get an overview. diff --git a/documentation/guide-microservice.asciidoc b/documentation/guide-microservice.asciidoc index 4c3cb806..001832a2 100644 --- a/documentation/guide-microservice.asciidoc +++ b/documentation/guide-microservice.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Microservices in devonfw The Microservices architecture is an approach for application development based on a series of _small_ services grouped under a business domain. Each individual service runs autonomously and communicating with each other through their APIs. That independence between the different services allows to manage (upgrade, fix, deploy, etc.) each one without affecting the rest of the system's services. In addition to that the microservices architecture allows to scale specific services when facing an increment of the requests, so the applications based on microservices are more flexible and stable, and can be adapted quickly to demand changes. diff --git a/documentation/guide-migration-oasp3-to-devon3.1.asciidoc b/documentation/guide-migration-oasp3-to-devon3.1.asciidoc index 37e3315e..1a7c804b 100644 --- a/documentation/guide-migration-oasp3-to-devon3.1.asciidoc +++ b/documentation/guide-migration-oasp3-to-devon3.1.asciidoc @@ -1,4 +1,8 @@ -# Migration Guide from oasp 3.0.0 to devon4j 3.1.0 migration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + += Migration Guide from oasp 3.0.0 to devon4j 3.1.0 migration - https://github.com/devonfw/devonfw-guide/blob/master/general/devcon-command-reference.asciidoc#devon4j-migrate[Automatic migration] with devcon doesn't work with parent pom's; you need to migrate every single subproject on it's own. - If your subproject's don't contain the old oasp4j or devon4j version number you have to copy your parent pom file into your child pom files and then use the migrate command. @@ -7,14 +11,14 @@ in the child pom file. - In case you are using eclipse, now you have to update and rebuild all your maven projects (alt + F5) -## JsonDeserializer: +== JsonDeserializer: 1. Change the super class from AbstractJsonDeserializer to JsonDeserializer 2. Implement unimplemented methods or change the methode signatur from Pageable deserializeNode(JsonNode node) to Pageable deserialize(JsonParser p, DeserializationContext context) 3. To get the JsonNode you need to use the following methods with the JsonParser p: JsonNode node = p.getCodec().readTree(p); 4. To get values of properties, you need to change from getRequiredValue(node, "property", String.class) to JacksonUtil.readValue(node, "property", String.class, false); -## QueryUtil update +== QueryUtil update whereString() (StringSearchConfigTo) method or similar: @@ -22,7 +26,7 @@ whereString() (StringSearchConfigTo) method or similar: 2. Delete the old import of oasp4j (for example import io.oasp.module.beanmapping.common.api.BeanMapper) and import the new class of devon4j (for example import com.devonfw.module.beanmapping.common.api.BeanMapper) -## logback.xml file +== logback.xml file 1. There maximum three chnages that needed to be done in the logback.xml file 2. Change the logging properties tag from @@ -31,17 +35,17 @@ devon4j (for example import com.devonfw.module.beanmapping.common.api.BeanMapper `` to `` 4. Change the appender console tag from `` to `` -## OaspPackage: +== OaspPackage: If you use the OaspPackage class you can replace it with the Devon4jPackage class -## AbstractLogic +== AbstractLogic 1. You can replace all net.sf.mmm.util imports with the appropriate com.devonfw.module imports. For example "import net.sf.mmm.util.entity.api.GenericEntity" to "import com.devonfw.module.basic.common.api.entity.GenericEntity" 2. Except the TransferObject and the AbstractTransferObject. These are replaced with the denvonfw AbstractTo. Example: "import net.sf.mmm.util.transferobject.api.AbstractTransferObject" or "import net.sf.mmm.util.transferobject.api.TransferObject" to "import com.devonfw.module.basic.common.api.to.AbstractTo". -## BeanDozerConfig +== BeanDozerConfig . Change the @ComponentScan annotation from `@ComponentScan(basePackages = { "io.oasp.module.beanmapping" })` to `@ComponentScan(basePackages = { "com.devonfw.module.beanmapping" })`. . Now you have to create a variable `DOZER_MAPPING_XML` with following content: `static final String DOZER_MAPPING_XML = "config/app/common/dozer-mapping.xml"`. @@ -55,7 +59,7 @@ https://github.com/DozerMapper/dozer/blob/master/docs/asciidoc/migration/v62-to- https://github.com/DozerMapper/dozer/blob/master/docs/asciidoc/migration/v63-to-v64.adoc . In addition, the semantics of `` seems to be changed. If you for example just needed to exclude files on mapping from a to b one-way, you now have to declare an empty mapping as well from b to a one-way without any field(-extension) declarations to enable mapping from b to a at all. See also https://github.com/DozerMapper/dozer/issues/605 and https://github.com/DozerMapper/dozer/issues/451 -## pom.xml +== pom.xml In the pom.xml file you have to do some manuall changes. You need to change all oasp dependencies to denvonfw dependencies. Here are some examples: @@ -265,12 +269,12 @@ In the pom.xml file you have to do some manuall changes. You need to change all ``` -## MutableGenericEntity +== MutableGenericEntity If you use the MutableGenericEntity<> class you have to change it to the PersistenceEntity<> class. Change the import "net.sf.mmm.util.entity.api.MutableGenericEntity" to "import com.devonfw.module.basic.common.api.entity.PersistenceEntity". -## CompositeTo +== CompositeTo If you use the CompositeTo class you should now use the AbstractTo class. Just change the import from "import net.sf.mmm.util.transferobject.api.CompositeTo" to "import com.devonfw.module.basic.common.api.to.AbstractTo". diff --git a/documentation/guide-migration-spring-quarkus.asciidoc b/documentation/guide-migration-spring-quarkus.asciidoc index 3791382f..c041d5ee 100644 --- a/documentation/guide-migration-spring-quarkus.asciidoc +++ b/documentation/guide-migration-spring-quarkus.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Migrate from Spring to Quarkus This guide will cover the migration process of a Spring application to a Quarkus application. There are already articles about migrating from Spring to Quarkus (e.g. https://developers.redhat.com/blog/2020/04/10/migrating-a-spring-boot-microservices-application-to-quarkus, https://dzone.com/articles/migrating-a-spring-boot-application-to-quarkus-cha). diff --git a/documentation/guide-monitoring.asciidoc b/documentation/guide-monitoring.asciidoc index da8dbb18..e81e18a0 100644 --- a/documentation/guide-monitoring.asciidoc +++ b/documentation/guide-monitoring.asciidoc @@ -1,6 +1,10 @@ :toc: toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Monitoring For monitoring a complex application landscape it is crucial to have an exact overview which applications are up and running and which are not and why. diff --git a/documentation/guide-openapi.asciidoc b/documentation/guide-openapi.asciidoc index 117c8362..70aa3ffe 100644 --- a/documentation/guide-openapi.asciidoc +++ b/documentation/guide-openapi.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = OpenAPI The link:https://spec.openapis.org/oas/latest.html[OpenAPI Specification (OAS)] defines a standard for describing RESTful web services in a machine- and human-readable format. OpenAPI allows REST APIs to be defined in a uniform manner. diff --git a/documentation/guide-queueing.asciidoc b/documentation/guide-queueing.asciidoc index 364c7db7..3373d784 100644 --- a/documentation/guide-queueing.asciidoc +++ b/documentation/guide-queueing.asciidoc @@ -1,6 +1,10 @@ :toc: toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = JMS == Introduction diff --git a/documentation/guide-repository.asciidoc b/documentation/guide-repository.asciidoc index 29e19827..f8f87764 100644 --- a/documentation/guide-repository.asciidoc +++ b/documentation/guide-repository.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Spring Data https://projects.spring.io/spring-data-jpa/[Spring Data JPA] is supported by both Spring and Quarkus. However, in Quarkus this approach still has some limitations. For detailed information, see the official https://quarkus.io/guides/spring-data-jpa[Quarkus Spring Data guide]. diff --git a/documentation/guide-rest-philosophy.asciidoc b/documentation/guide-rest-philosophy.asciidoc index cbcb71bf..b4036673 100644 --- a/documentation/guide-rest-philosophy.asciidoc +++ b/documentation/guide-rest-philosophy.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = REST Philosophy REST and RESTful often implies very strict and specific rules and conventions. diff --git a/documentation/guide-rest.asciidoc b/documentation/guide-rest.asciidoc index c071d921..414978a5 100644 --- a/documentation/guide-rest.asciidoc +++ b/documentation/guide-rest.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = REST REST (https://en.wikipedia.org/wiki/Representational_state_transfer[REpresentational State Transfer]) is an inter-operable protocol for link:guide-service-layer.asciidoc[services] that is more lightweight than link:guide-soap.asciidoc[SOAP]. However, it is no real standard and can cause confusion (see link:https://github.com/devonfw/devon4j/blob/master/documentation/guide-rest-philosophy.asciidoc[REST philosophy]). diff --git a/documentation/guide-scm.asciidoc b/documentation/guide-scm.asciidoc index c0d7b13a..554bb263 100644 --- a/documentation/guide-scm.asciidoc +++ b/documentation/guide-scm.asciidoc @@ -1,6 +1,10 @@ :toc: toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Software-Configuration-Management TODO diff --git a/documentation/guide-security.asciidoc b/documentation/guide-security.asciidoc index 88b31b4d..db1974d4 100644 --- a/documentation/guide-security.asciidoc +++ b/documentation/guide-security.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Security //Fixed Typo Security is todays most important cross-cutting concern of an application and an enterprise IT-landscape. We seriously care about security and give you detailed guides to prevent pitfalls, vulnerabilities, and other disasters. While many mistakes can be avoided by following our guidelines you still have to consider security and think about it in your design and implementation. The security guide will not only automatically prevent you from any harm, but will provide you hints and best practices already used in different software products. diff --git a/documentation/guide-service-client.asciidoc b/documentation/guide-service-client.asciidoc index ab3c917a..a3b9289c 100644 --- a/documentation/guide-service-client.asciidoc +++ b/documentation/guide-service-client.asciidoc @@ -2,6 +2,10 @@ :icons: font toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Service Client This guide is about consuming (calling) services from other applications (micro-services). For providing services, see the link:guide-service-layer.asciidoc[Service-Layer Guide]. Services can be consumed by the link:guide-client-layer.asciidoc[client] or the server. As the client is typically not written in Java, you should consult the according guide for your client technology. In case you want to call a service within your Java code, this guide is the right place to get help. diff --git a/documentation/guide-service-layer.asciidoc b/documentation/guide-service-layer.asciidoc index a261e719..570ff96d 100644 --- a/documentation/guide-service-layer.asciidoc +++ b/documentation/guide-service-layer.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Service Layer The service layer is responsible for exposing functionality made available by the link:guide-logic-layer.asciidoc[logical layer] to external consumers over a network via xref:protocol[technical protocols]. diff --git a/documentation/guide-service-versioning.asciidoc b/documentation/guide-service-versioning.asciidoc index ba0cdf0b..d4fdcf84 100644 --- a/documentation/guide-service-versioning.asciidoc +++ b/documentation/guide-service-versioning.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Service-Versioning This guide describes the aspect and details about versioning of link:guide-service-layer.asciidoc[services] diff --git a/documentation/guide-soap.asciidoc b/documentation/guide-soap.asciidoc index 7dfe651a..7ab484ff 100644 --- a/documentation/guide-soap.asciidoc +++ b/documentation/guide-soap.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = SOAP https://en.wikipedia.org/wiki/SOAP[SOAP] is a common protocol for link:guide-service-layer.asciidoc[services] that is rather complex and heavy. It allows to build inter-operable and well specified services (see WSDL). SOAP is transport neutral what is not only an advantage. We strongly recommend to use HTTPS transport and ignore additional complex standards like WS-Security and use established HTTP-Standards such as RFC2617 (and RFC5280). //There is no SOAP example in our application -maybe keep this as a general example?- diff --git a/documentation/guide-sql.asciidoc b/documentation/guide-sql.asciidoc index 6efa1141..9399417b 100644 --- a/documentation/guide-sql.asciidoc +++ b/documentation/guide-sql.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = SQL For general guides on dealing or avoiding SQL, preventing SQL-injection, etc. you should study link:guide-domain-layer.asciidoc[domain layer]. diff --git a/documentation/guide-structure-classic.asciidoc b/documentation/guide-structure-classic.asciidoc index afc99b39..bd6d88ce 100644 --- a/documentation/guide-structure-classic.asciidoc +++ b/documentation/guide-structure-classic.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Classic project structure In this section we describe the classic project structure as initially proposed for Java in devonfw. diff --git a/documentation/guide-structure-modern.asciidoc b/documentation/guide-structure-modern.asciidoc index 88697e68..7c55f5dc 100644 --- a/documentation/guide-structure-modern.asciidoc +++ b/documentation/guide-structure-modern.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Modern project structure With trends such as cloud, microservices, lean, and agile, we decided for a more modern project structure that fits better to recent market trends. diff --git a/documentation/guide-structure.asciidoc b/documentation/guide-structure.asciidoc index a6071719..f03f3623 100644 --- a/documentation/guide-structure.asciidoc +++ b/documentation/guide-structure.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Project structure In devonfw we want to give clear structure and guidance for building applications. diff --git a/documentation/guide-testing-snapshots.asciidoc b/documentation/guide-testing-snapshots.asciidoc index c5013da9..0334a45c 100644 --- a/documentation/guide-testing-snapshots.asciidoc +++ b/documentation/guide-testing-snapshots.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Testing devon4j SNAPSHOT releases Whenever a story in devon4j is completed by merging a https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests[PR], diff --git a/documentation/guide-testing.asciidoc b/documentation/guide-testing.asciidoc index 0f5138dc..2df59cec 100644 --- a/documentation/guide-testing.asciidoc +++ b/documentation/guide-testing.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Testing == General best practices diff --git a/documentation/guide-text-search.asciidoc b/documentation/guide-text-search.asciidoc index 3c5be55b..c39dfe1e 100644 --- a/documentation/guide-text-search.asciidoc +++ b/documentation/guide-text-search.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Full Text Search If you want to all your users fast and simple searches with just a single search field (like in google), you need full text indexing and search support. diff --git a/documentation/guide-transactions.asciidoc b/documentation/guide-transactions.asciidoc index 1fc3b386..3741dfa9 100644 --- a/documentation/guide-transactions.asciidoc +++ b/documentation/guide-transactions.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Transaction Handling For transaction handling we link:guide-aop.asciidoc[AOP] to add transaction control via annotations as aspect. diff --git a/documentation/guide-transferobject.asciidoc b/documentation/guide-transferobject.asciidoc index ac67a54b..9e80c532 100644 --- a/documentation/guide-transferobject.asciidoc +++ b/documentation/guide-transferobject.asciidoc @@ -1,5 +1,11 @@ :toc: macro toc::[] + + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Transfer-Objects The technical data model is defined in form of link:guide-jpa.asciidoc#entity[persistent entities]. diff --git a/documentation/guide-usecase.asciidoc b/documentation/guide-usecase.asciidoc index 26e1db93..208200dd 100644 --- a/documentation/guide-usecase.asciidoc +++ b/documentation/guide-usecase.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = UseCase A use-case is a small unit of the link:guide-logic-layer.asciidoc[logic layer] responsible for an operation on a particular link:guide-jpa.asciidoc#entity[entity] (business object). We leave it up to you to decide whether you want to define an interface (API) for each use-case or provide an implementation directly. diff --git a/documentation/guide-validation.asciidoc b/documentation/guide-validation.asciidoc index 140c6269..79f72600 100644 --- a/documentation/guide-validation.asciidoc +++ b/documentation/guide-validation.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Validation Validation is about checking syntax and semantics of input data. Invalid data is rejected by the application. diff --git a/documentation/guide-xml.asciidoc b/documentation/guide-xml.asciidoc index 80f19b38..d93013fb 100644 --- a/documentation/guide-xml.asciidoc +++ b/documentation/guide-xml.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = XML http://en.wikipedia.org/wiki/XML[XML] (Extensible Markup Language) is a W3C standard format for structured information. It has a large eco-system of additional standards and tools. diff --git a/documentation/performance-comparision-spring-quarkus.asciidoc b/documentation/performance-comparision-spring-quarkus.asciidoc index 4dea66f5..033badcd 100644 --- a/documentation/performance-comparision-spring-quarkus.asciidoc +++ b/documentation/performance-comparision-spring-quarkus.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Performance comparison between Spring and Quarkus Quarkus offers a big advantage in resource consumption compared to a Spring application. Especially in native mode, the memory footprint of a Quarkus application is extremely low, which can be a deciding factor in real-world environments. diff --git a/documentation/quarkus.asciidoc b/documentation/quarkus.asciidoc index cd85ec0f..8543ec74 100644 --- a/documentation/quarkus.asciidoc +++ b/documentation/quarkus.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Quarkus https://quarkus.io[Quarkus] is a Java framework for building cloud-native apps. diff --git a/documentation/quarkus/getting-started-for-spring-developers.asciidoc b/documentation/quarkus/getting-started-for-spring-developers.asciidoc index b084fa55..25e3e113 100644 --- a/documentation/quarkus/getting-started-for-spring-developers.asciidoc +++ b/documentation/quarkus/getting-started-for-spring-developers.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Getting started with Quarkus for Spring developers As a Spring developer, you have heard more and more about Quarkus: its pros and cons, its fast growth etc. So, you decided to adopt/try Quarkus for your (next) project(s) and are wondering where to go next and what you need to pay attention to when moving from Spring to Quarkus. diff --git a/documentation/quarkus/getting-started-quarkus.asciidoc b/documentation/quarkus/getting-started-quarkus.asciidoc index 260064e3..88945fcc 100644 --- a/documentation/quarkus/getting-started-quarkus.asciidoc +++ b/documentation/quarkus/getting-started-quarkus.asciidoc @@ -1,3 +1,7 @@ +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Quarkus Quickstart This guide serves as a quickstart on how to create a Quarkus app, briefly presenting the key functionalities that Quarkus provides, both for beginners and experienced developers. diff --git a/documentation/quarkus/guide-authentication-quarkus.asciidoc b/documentation/quarkus/guide-authentication-quarkus.asciidoc index 59e912a0..a5e68f34 100644 --- a/documentation/quarkus/guide-authentication-quarkus.asciidoc +++ b/documentation/quarkus/guide-authentication-quarkus.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Quarkus Authentication Quarkus supports different authentication mechanisms through different extensions. For example: diff --git a/documentation/quarkus/guide-beanmapping-quarkus.asciidoc b/documentation/quarkus/guide-beanmapping-quarkus.asciidoc index e9ead70d..fec65fd8 100644 --- a/documentation/quarkus/guide-beanmapping-quarkus.asciidoc +++ b/documentation/quarkus/guide-beanmapping-quarkus.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Bean mapping with Quarkus This guide will show bean-mapping, in particular for a Quarkus application. We recommend using https://mapstruct.org/[MapStruct] with a Quarkus application because the other bean-mapper frameworks use Java reflections. They are not supported in GraalVm right now and cause problems when building native applications. MapStruct is a code generator that greatly simplifies the implementation of mappings between Java bean types based on a convention over configuration approach. The mapping code will be generated at compile-time and uses plain method invocations and is thus fast, type-safe, and easy to understand. MapStruct has to be configured to not use Java reflections, which will be shown in this guide. diff --git a/documentation/quarkus/guide-exception-handling.asciidoc b/documentation/quarkus/guide-exception-handling.asciidoc index c4055adf..dc51b05c 100644 --- a/documentation/quarkus/guide-exception-handling.asciidoc +++ b/documentation/quarkus/guide-exception-handling.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Exception Handling in Quarkus For link:../guide-exceptions.asciidoc[handling exceptions] within a Spring application, devon4j provides the https://github.com/devonfw/devon4j/tree/master/modules/rest[devon4j-rest module], which provides a https://github.com/devonfw/devon4j/blob/develop/modules/rest/src/main/java/com/devonfw/module/rest/service/impl/RestServiceExceptionFacade.java[`RestServiceExceptionFacade`] to handle all exceptions in a consistent way. Since the module is not suitable for Quarkus, we need to implement this ourselves. diff --git a/documentation/quarkus/guide-native-image.asciidoc b/documentation/quarkus/guide-native-image.asciidoc index 48189250..4e3a2089 100644 --- a/documentation/quarkus/guide-native-image.asciidoc +++ b/documentation/quarkus/guide-native-image.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Building a native image Quarkus provides the ability to create a native executable of the application called _https://quarkus.io/guides/building-native-image[native image]_. diff --git a/documentation/quarkus/guide-quarkus-configuration.asciidoc b/documentation/quarkus/guide-quarkus-configuration.asciidoc index 7f3e0883..5981667a 100644 --- a/documentation/quarkus/guide-quarkus-configuration.asciidoc +++ b/documentation/quarkus/guide-quarkus-configuration.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Configuration link:quarkus.asciidoc[Quarkus] provides a comprehensive guide on configuration https://quarkus.io/guides/config-reference[here]. diff --git a/documentation/quarkus/guide-quarkus-testing.asciidoc b/documentation/quarkus/guide-quarkus-testing.asciidoc index e3071bd6..e2a98518 100644 --- a/documentation/quarkus/guide-quarkus-testing.asciidoc +++ b/documentation/quarkus/guide-quarkus-testing.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Testing == Configuration diff --git a/documentation/quarkus/quarkus-template.asciidoc b/documentation/quarkus/quarkus-template.asciidoc index 9fb06f5f..dbb2cf12 100644 --- a/documentation/quarkus/quarkus-template.asciidoc +++ b/documentation/quarkus/quarkus-template.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Quarkus template https://code.quarkus.io/?g=org.devonfw&e=resteasy&e=resteasy-jackson&e=hibernate-validator&e=hibernate-orm&e=micrometer[Quarkus Code Generator] is provides many alternative technologies and libraries that can be integrated into a project. Detailed guides on multiple topics can be found https://quarkus.io/guides/[here]. diff --git a/documentation/spring.asciidoc b/documentation/spring.asciidoc index c34a4044..a5529417 100644 --- a/documentation/spring.asciidoc +++ b/documentation/spring.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Spring https://spring.io[Spring] is the most famous and established Java framework. diff --git a/documentation/spring/guide-authentication-spring.asciidoc b/documentation/spring/guide-authentication-spring.asciidoc index 97cd2731..d09a76b0 100644 --- a/documentation/spring/guide-authentication-spring.asciidoc +++ b/documentation/spring/guide-authentication-spring.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Spring Security We use https://projects.spring.io/spring-security/[spring-security] as a framework for authentication purposes. diff --git a/documentation/spring/guide-beanmapping-spring.asciidoc b/documentation/spring/guide-beanmapping-spring.asciidoc index 1acb2c57..402eca22 100644 --- a/documentation/spring/guide-beanmapping-spring.asciidoc +++ b/documentation/spring/guide-beanmapping-spring.asciidoc @@ -1,4 +1,10 @@ + + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Bean Mapping in devon4j-spring We have developed a solution that uses a `BeanMapper` that allows to abstract from the underlying implementation. As mentioned in the link:../guide-beanmapping.asccidoc[general bean mapping guide], we started with http://dozer.sourceforge.net/documentation/about.html[Dozer] a Java Bean to Java Bean mapper that recursively copies data from one object to another. Now we recommend using https://orika-mapper.github.io/orika-docs/[Orika]. This guide will show an introduction to Orika and Dozer bean-mapper. diff --git a/documentation/spring/guide-cors-spring.asciidoc b/documentation/spring/guide-cors-spring.asciidoc index 25d59414..361a3f2e 100644 --- a/documentation/spring/guide-cors-spring.asciidoc +++ b/documentation/spring/guide-cors-spring.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = CORS configuration in Spring == Dependency diff --git a/documentation/spring/guide-devon4j-spring-repository.asciidoc b/documentation/spring/guide-devon4j-spring-repository.asciidoc index 2ee771df..5d0196bf 100644 --- a/documentation/spring/guide-devon4j-spring-repository.asciidoc +++ b/documentation/spring/guide-devon4j-spring-repository.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Spring Data in devon4j-spring In devon4j-spring, https://projects.spring.io/spring-data-jpa/[spring-data-jpa] is provided via http://repo1.maven.org/maven2/com/devonfw/java/starters/devon4j-starter-spring-data-jpa/[devon4j-starter-spring-data-jpa] extension, which provides advanced integration (esp. for QueryDSL). diff --git a/documentation/spring/guide-jwt-spring.asciidoc b/documentation/spring/guide-jwt-spring.asciidoc index df7b2d2f..693a8a00 100644 --- a/documentation/spring/guide-jwt-spring.asciidoc +++ b/documentation/spring/guide-jwt-spring.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = JWT Spring-Starter == Keystore diff --git a/documentation/spring/guide-kafka-spring.asciidoc b/documentation/spring/guide-kafka-spring.asciidoc index 5fbb34bf..233e8f79 100644 --- a/documentation/spring/guide-kafka-spring.asciidoc +++ b/documentation/spring/guide-kafka-spring.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Kafka This guide explains how Spring Kafka is used in devonfw applications. It focuses on aspects which are special to devonfw if you want to learn about spring-kafka you should adhere to springs references documentation. diff --git a/documentation/spring/guide-querydsl-spring.asciidoc b/documentation/spring/guide-querydsl-spring.asciidoc index 4c464097..043e5bd4 100644 --- a/documentation/spring/guide-querydsl-spring.asciidoc +++ b/documentation/spring/guide-querydsl-spring.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = QueryDSL in devon4j-spring To implement dynamic queries, devon4j suggests the use of QueryDSL. QueryDSL uses metaclasses generated from entity classes at build time. devon4j-spring provides a way to use QueryDSL without the need for code generation. For this, devon4j provides the interface https://github.com/devonfw/devon4j/blob/master/modules/jpa-spring-data/src/main/java/com/devonfw/module/jpa/dataaccess/api/data/DefaultRepository.java[DefaultRepository] that your repository needs to extend and the https://github.com/devonfw/devon4j/blob/master/modules/jpa-basic/src/main/java/com/devonfw/module/jpa/dataaccess/api/QueryUtil.java[QueryUtil] helper class to build your queries. diff --git a/documentation/spring/guide-service-client-spring.asciidoc b/documentation/spring/guide-service-client-spring.asciidoc index 827dd039..5f5eed41 100644 --- a/documentation/spring/guide-service-client-spring.asciidoc +++ b/documentation/spring/guide-service-client-spring.asciidoc @@ -2,6 +2,10 @@ :icons: font toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Service Client in devon4j-spring This guide is about consuming (calling) services from other applications (micro-services) in devon4j-spring. diff --git a/documentation/spring/guide-spring-configuration.asciidoc b/documentation/spring/guide-spring-configuration.asciidoc index 2cda469a..33e22d8a 100644 --- a/documentation/spring/guide-spring-configuration.asciidoc +++ b/documentation/spring/guide-spring-configuration.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Configuration == Internal Application Configuration diff --git a/documentation/spring/guide-spring-testing.asciidoc b/documentation/spring/guide-spring-testing.asciidoc index efd82d8e..f8f903dc 100644 --- a/documentation/spring/guide-spring-testing.asciidoc +++ b/documentation/spring/guide-spring-testing.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Testing == Implementation diff --git a/documentation/tutorial-newapp.asciidoc b/documentation/tutorial-newapp.asciidoc index f0a45854..0d923708 100644 --- a/documentation/tutorial-newapp.asciidoc +++ b/documentation/tutorial-newapp.asciidoc @@ -1,6 +1,10 @@ :toc: macro toc::[] +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + +''' + = Creating a new application == Running the archetype From 00562ccc4a91c11797e15204bfcd10ea33b34a91 Mon Sep 17 00:00:00 2001 From: denise-khuu <74537227+denise-khuu@users.noreply.github.com> Date: Mon, 21 Nov 2022 09:29:54 +0100 Subject: [PATCH 10/10] Feature/new page announcement (#578) * bugfix syntax error # -> = * added warning * remove warning * added warning --- documentation/12-factor-app-devon4j.asciidoc | 6 +- documentation/Home.asciidoc | 8 +- .../Spring-native-vs-Quarkus.asciidoc | 24 +++++- .../alternative-microservice-netflix.asciidoc | 78 ++++++++++++++++++- documentation/architecture.asciidoc | 18 ++++- .../build-release-run-12factor.asciidoc | 6 +- documentation/coding-conventions.asciidoc | 42 +++++++++- documentation/coding-tools.asciidoc | 6 +- ...cision-between-Spring-and-Quarkus.asciidoc | 22 +++++- .../decision-service-framework.asciidoc | 10 ++- documentation/devon4j-doc.asciidoc | 7 +- documentation/devon4j.asciidoc | 16 +++- .../guide-access-control-schema.asciidoc | 8 +- documentation/guide-access-control.asciidoc | 34 +++++++- documentation/guide-accessibility.asciidoc | 6 +- documentation/guide-aop.asciidoc | 12 ++- documentation/guide-api-first.asciidoc | 20 ++++- documentation/guide-apm.asciidoc | 14 +++- documentation/guide-auditing.asciidoc | 6 +- documentation/guide-batch-layer.asciidoc | 38 ++++++++- documentation/guide-beanmapping.asciidoc | 8 +- documentation/guide-blob-support.asciidoc | 10 +-- documentation/guide-caching.asciidoc | 16 +++- documentation/guide-client-layer.asciidoc | 8 +- documentation/guide-common.asciidoc | 6 +- documentation/guide-component-facade.asciidoc | 10 ++- documentation/guide-component.asciidoc | 14 +++- .../guide-configuration-mapping.asciidoc | 12 ++- documentation/guide-configuration.asciidoc | 20 ++++- documentation/guide-cors-support.asciidoc | 10 ++- documentation/guide-csrf.asciidoc | 20 ++++- documentation/guide-dao.asciidoc | 12 ++- documentation/guide-data-permission.asciidoc | 16 +++- documentation/guide-dataaccess-layer.asciidoc | 8 +- .../guide-database-migration.asciidoc | 8 +- documentation/guide-datatype.asciidoc | 18 ++++- .../guide-dependency-injection.asciidoc | 22 +++++- documentation/guide-domain-layer.asciidoc | 6 +- documentation/guide-dto.asciidoc | 8 +- documentation/guide-eto-cto.asciidoc | 14 ++-- documentation/guide-exceptions.asciidoc | 14 +++- documentation/guide-feature-toggle.asciidoc | 24 +++++- documentation/guide-flyway.asciidoc | 12 ++- documentation/guide-i18n.asciidoc | 12 +-- documentation/guide-jdk.asciidoc | 34 +++++++- documentation/guide-jee.asciidoc | 8 +- documentation/guide-jms.asciidoc | 14 +++- documentation/guide-jmx.asciidoc | 6 +- documentation/guide-jpa-idref.asciidoc | 14 +++- documentation/guide-jpa-performance.asciidoc | 10 ++- documentation/guide-jpa-query.asciidoc | 28 ++++++- documentation/guide-jpa.asciidoc | 64 ++++++++++++++- documentation/guide-json.asciidoc | 12 ++- documentation/guide-jwt.asciidoc | 6 +- documentation/guide-kafka.asciidoc | 6 +- documentation/guide-liquibase.asciidoc | 10 ++- documentation/guide-log-monitoring.asciidoc | 10 ++- documentation/guide-logging.asciidoc | 34 +++++++- documentation/guide-logic-layer.asciidoc | 12 ++- documentation/guide-lombok.asciidoc | 12 ++- documentation/guide-microservice.asciidoc | 6 +- ...guide-migration-oasp3-to-devon3.1.asciidoc | 24 +++++- .../guide-migration-spring-quarkus.asciidoc | 24 +++++- documentation/guide-monitoring.asciidoc | 10 ++- documentation/guide-openapi.asciidoc | 20 ++++- documentation/guide-queueing.asciidoc | 14 +++- documentation/guide-repository.asciidoc | 24 +++++- documentation/guide-rest-philosophy.asciidoc | 34 +++++++- documentation/guide-rest.asciidoc | 30 ++++++- documentation/guide-scm.asciidoc | 16 +++- documentation/guide-security.asciidoc | 16 +++- documentation/guide-service-client.asciidoc | 10 ++- documentation/guide-service-layer.asciidoc | 16 +++- .../guide-service-versioning.asciidoc | 16 +++- documentation/guide-soap.asciidoc | 16 +++- documentation/guide-sql.asciidoc | 12 ++- .../guide-structure-classic.asciidoc | 16 +++- documentation/guide-structure-modern.asciidoc | 14 +++- documentation/guide-structure.asciidoc | 6 +- .../guide-testing-snapshots.asciidoc | 6 +- documentation/guide-testing.asciidoc | 50 +++++++++++- documentation/guide-text-search.asciidoc | 10 ++- documentation/guide-transactions.asciidoc | 14 +++- documentation/guide-transferobject.asciidoc | 8 +- documentation/guide-usecase.asciidoc | 16 +++- documentation/guide-validation.asciidoc | 16 +++- documentation/guide-xml.asciidoc | 14 +++- ...rmance-comparision-spring-quarkus.asciidoc | 6 +- documentation/quarkus.asciidoc | 12 ++- ...ing-started-for-spring-developers.asciidoc | 6 +- .../quarkus/getting-started-quarkus.asciidoc | 40 +++++++++- .../guide-authentication-quarkus.asciidoc | 6 +- .../guide-beanmapping-quarkus.asciidoc | 20 ++++- .../quarkus/guide-exception-handling.asciidoc | 8 +- .../quarkus/guide-native-image.asciidoc | 14 +++- .../guide-quarkus-configuration.asciidoc | 26 ++++++- .../quarkus/guide-quarkus-testing.asciidoc | 16 +++- .../quarkus/quarkus-template.asciidoc | 8 +- documentation/spring.asciidoc | 16 +++- .../guide-authentication-spring.asciidoc | 8 +- .../spring/guide-beanmapping-spring.asciidoc | 18 +++-- .../spring/guide-cors-spring.asciidoc | 10 ++- .../guide-devon4j-spring-repository.asciidoc | 14 +++- .../spring/guide-jwt-spring.asciidoc | 18 ++++- .../spring/guide-kafka-spring.asciidoc | 40 +++++++++- .../spring/guide-querydsl-spring.asciidoc | 10 ++- .../guide-service-client-spring.asciidoc | 30 ++++++- .../guide-spring-configuration.asciidoc | 32 +++++++- .../spring/guide-spring-testing.asciidoc | 16 +++- documentation/tutorial-newapp.asciidoc | 20 ++++- 110 files changed, 1365 insertions(+), 456 deletions(-) diff --git a/documentation/12-factor-app-devon4j.asciidoc b/documentation/12-factor-app-devon4j.asciidoc index 0242449e..337add38 100644 --- a/documentation/12-factor-app-devon4j.asciidoc +++ b/documentation/12-factor-app-devon4j.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = 12-factor-app with devon4j +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This document mainly focuses on discussing how can you create 12 factor app with devon4j. To know more about this 12 factors you can refer https://12factor.net/[here] . Twelve factor is mainly focus on creating cloud native applications. These are the guidelines on what factors you need to consider in different stages of application lifecycle. diff --git a/documentation/Home.asciidoc b/documentation/Home.asciidoc index d0dd4393..47a3872c 100644 --- a/documentation/Home.asciidoc +++ b/documentation/Home.asciidoc @@ -1,9 +1,7 @@ -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = devonfw for Java (devon4j) +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Welcome to the Java edition of devonfw. devon4j is documented by a platform guide (see the side-bar of this wiki) to be used in your projects. You will find the latest stable versions of documents generated from this wiki here: @@ -12,4 +10,6 @@ You will find the latest stable versions of documents generated from this wiki h If you want to search the wiki you might want to try https://github.com/linyows/github-wiki-search[github-wiki-search]. == For contributors + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Contributions and improvements to devonfw are more than welcome. Please read our https://github.com/devonfw/.github/blob/master/CONTRIBUTING.asciidoc#contributing[contributing guide] to get started. diff --git a/documentation/Spring-native-vs-Quarkus.asciidoc b/documentation/Spring-native-vs-Quarkus.asciidoc index 2f0af01f..76a6918f 100644 --- a/documentation/Spring-native-vs-Quarkus.asciidoc +++ b/documentation/Spring-native-vs-Quarkus.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Spring Native vs Quarkus +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Nowadays, it is very common to write an application and deploy it to a cloud. Serverless computing and Function-as-a-Service (FaaS) have become very popular. @@ -16,6 +14,8 @@ https://docs.spring.io/spring-native/docs/current/reference/htmlsingle/#overview == Quarkus +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus is a full-stack, Kubernetes-native Java framework made for JVMs. With its container-first-philosophy and its native compilation with GraalVM, Quarkus optimizes Java for containers with low memory usage and fast startup times. Quarkus achieves this in the following ways: @@ -37,10 +37,16 @@ This gives Quarkus the potential for a great platform for serverless cloud and K == Spring Native +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. *The current version of Spring Native 0.10.5 is designed to be used with Spring Boot 2.5.6* ==== +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Like Quarkus, Spring Native provides support for compiling Spring applications to native executables using the GraalVM native-image compiler deisgned to be packaged in lightweight containers. Spring Native is composed of the following modules: @@ -65,6 +71,8 @@ Spring Native is composed of the following modules: == Native compilation with GraalVM +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus and Spring Native both use GraalVM for native compilation. Using a native image provides some key advantages, such as instant startup, instant peak performance, and reduced memory consumption. However, there are also some drawbacks: Creating a native image is a heavy process that is slower than a regular application. A native image also has fewer runtime optimizations after its warmup. Furthermore, it is less mature than the JVM and comes with some different behaviors. *Key characteristics:* @@ -81,6 +89,8 @@ There are https://github.com/oracle/graal/blob/master/docs/reference-manual/nati == Build time and start time for apps +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + [cols=",,",options="header",] |=== |Framework |build time |start time @@ -90,6 +100,8 @@ There are https://github.com/oracle/graal/blob/master/docs/reference-manual/nati == Memory footprints +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + [cols=",",options="header",] |=== |Framework |memory footprint @@ -99,6 +111,8 @@ There are https://github.com/oracle/graal/blob/master/docs/reference-manual/nati == Considering devonfw best practices +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + As of now, devonfw actively supports Spring but not Spring Native. Although Quarkus has been released to a stable release in early 2021, it has been already used in multiple big projects successfully showing its potential to implement cloud native services with low resource consumption matching the needs of scalability and resilience in cloud native environments. With major stakeholders behind the open source community like Red Hat, its development and growth from its kickoff to the current state is very impressive and really shows the market needs and focus. @@ -111,6 +125,8 @@ Spring. == General recommendations and conclusion +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus and Spring Native both have their own use cases. Under the consideration of the limitations of GraalVM to be used for native images built by Quarkus and Spring Native, there is a strong recommendation towards Quarkus from devonfw. One essential differentiation has to be made on the decision for native or against native applications - the foreseen performance optimization of the JIT compiler of the JVM, which is not available anymore in a native image deployment. For sure, both component frameworks will also run on a JVM getting advantage again from JIT compilation, but depending on the overall landscape then, it is recommended to stay with the knowledge of the available teams, e.g. continue making use of devon4j based on spring or even if already in that state also here make use of Quarkus on JVM. diff --git a/documentation/alternative-microservice-netflix.asciidoc b/documentation/alternative-microservice-netflix.asciidoc index 6126604c..15af26db 100644 --- a/documentation/alternative-microservice-netflix.asciidoc +++ b/documentation/alternative-microservice-netflix.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - == Microservices based on Netflix-Tools +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Devonfw microservices approach is based on http://cloud.spring.io/spring-cloud-netflix/[Spring Cloud Netflix], that provides all the main components for microservices integrated within Spring Boot context. @@ -18,6 +16,8 @@ Let's explain each component ==== Service Discovery - Eureka +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + link:http://cloud.spring.io/spring-cloud-static/spring-cloud-netflix/1.3.0.M1/#service_discovery_eureka_clients[Eureka] is a server to register and locate the microservices. The main function for _Eureka_ is to register the different instances of the microservices, its location, its state and other metadata. It works in a simple way, during the start of each microservice, this communicates with the _Eureka_ server to notify its availability and to send the metadata. The microservice will continue to notify its status to the Eureka server every 30 seconds (default time on Eureka server properties). This value can be changed in the configuration of the component. @@ -28,25 +28,35 @@ In addition, it serves as a catalog to locate a specific microservice when routi ==== Circuit Breaker - Hystrix +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + http://cloud.spring.io/spring-cloud-static/spring-cloud-netflix/1.3.0.M1/#circuit_breaker_hystrix_clients[Hystrix] is a library that implements the https://martinfowler.com/bliki/CircuitBreaker.html[Circuit Breaker] pattern. Its main functionality is to improve the reliability of the system, isolating the entry points of the microservices, preventing the cascading failure from the lower levels of the application all the way up to the user. In addition to that, it allows developers to provide a fallback in case of error. _Hystrix_ manages the requests to a service, and in case that the microservice doesn't response, allows to implement an alternative to the request. ==== Client Side Load Balancer - Ribbon +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + http://cloud.spring.io/spring-cloud-static/spring-cloud-netflix/1.3.0.M1/#spring-cloud-ribbon[Ribbon] is a library designed as client side load balancer. Its main feature is to integrate with _Eureka_ to discover the instances of the microservices and their metadata. In that way the _Ribbon_ is able to calculate which of the available instances of a microservice is the most appropriate for the client, when facing a request. ==== REST Client - Feign + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. http://cloud.spring.io/spring-cloud-static/spring-cloud-netflix/1.3.0.M1/#spring-cloud-feign[Feign] is a REST client to make calls to other microservices. The strength of Feign is that it integrates seamlessly with _Ribbon_ and _Hystrix_, and its implementation is through annotations, which greatly facilitates this task to the developer. Using annotations, Spring-cloud generates, automatically, a fully configured REST client. ==== Router and Filter - Zuul +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + link:http://cloud.spring.io/spring-cloud-static/spring-cloud-netflix/1.3.0.M1/#router_and_filter_zuul[Zuul] is the entry point of the apps based on Spring-cloud microservices. It allows dynamic routing, load balancing, monitoring and securing of requests. By default _Zuul_ uses _Ribbon_ to locate, through Eureka, the instances of the microservice that it wants to invoke and sends the requests within a _Hystrix Command_, taking advantage of its functionality. === How to create microservices in devonfw? +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Follow the instructions in the link below to set up devonfw distribution <> @@ -55,10 +65,14 @@ Next, install devonfw modules and dependencies ==== Step 1: Open the console +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + 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 +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Run the following command in the console to change directory to devonfw module [source,bash] @@ -68,6 +82,8 @@ cd workspaces\examples\devonfw ==== Step 3: Install +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To install modules and dependencies, you need to execute the following command: [source,bash] @@ -90,6 +106,8 @@ That second approach, using the devonfw microservices archetype, will generate a === devonfw archetypes +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To simplify starting with projects based on microservices, devonfw includes two archetypes to generate pre-configured projects that include all the basic components of the _Spring Cloud_ implementation. - *archetypes-microservices-infra*: generates a project with the needed infrastructure services to manage microservices. Includes the _Eureka_ service, _Zuul_ service and the authentication service. @@ -98,6 +116,8 @@ To simplify starting with projects based on microservices, devonfw includes two === Create New Microservices infrastructure application +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To generate a new microservices infrastructure application through the devonfw archetype you only need to open a devonfw console (_console.bat_ script) and follow the same steps described in <>. But, instead of using the _standard_ archetype, we must provide the special infrastructure archetype `archetype-microservice-infra`. Remember to provide your own values for _DgroupId_, _DartifactId_, _Dversion_ and _Dpackage_ parameters, Also provide the -DarchetypeVersion with latest value: [source, bash] @@ -111,24 +131,32 @@ image::images/microservices/microservices_02.png[,width="150", link="images/micr ==== service-eureka module +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This module contains the needed classes and configuration to start a _Eureka_ server. This service runs by default on port _8761_ although ti can be changed in the `application.properties` file of the project. ==== service-zuul module +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This module contains all the needed classes and configuration to start a _Zuul_ server, that will be in charge of the routing and filter of the requests. This service by default runs on port _8081_ but, as we already mentioned, it can be changed through the file `application.properties` of the project. ==== service-auth module +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This module runs an authentication and authorization mock microservice that allows to generate a security token to make calls to the rest of microservices. This module is only providing a basic structure, the security measures must be implemented fitting the requirements of each project (authentication through DB, SSO, LDAP, OAuth,...) This service runs by default on port _9999_, although, as in previous services, it can be edited in the `application.properties` file. === Create New Microservices Application +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To generate a new microservice project through the devonfw archetype, as in previous archetype example, you can follow the instructions explained in <>. But, instead of using the _standard_ archetype, we must provide the special microservices archetype `archetype-microservices`. Open a devonfw console (_console.bat_ script) and launch a _Maven_ command like the following (provide your own values for _DgroupId_, _DartifactId_, _Dversion_ and _Dpackage_ parameters, also provide the -DarchetypeVersion with latest value): [source, bash] @@ -142,19 +170,27 @@ The created microservice runs by default on port _9001_ and has the `context-pat === How to use microservices in devonfw +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In the following sections we are going to provide some patterns to manage microservices in devonfw using the archetype, alongside the options that each of the available modules offer. ==== Eureka service +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We are going to review the general options for the _Eureka_ service. If you are interested in getting more details you can visit the official site for http://cloud.spring.io/spring-cloud-static/spring-cloud-netflix/1.3.0.M1/#service_discovery_eureka_clients[Spring Cloud Eureka clients]. To create an _Eureka_ server you only need to create a new _Spring Boot_ application and add the `@EnableEurekaServer` to the main class. [NOTE] ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The provided archetype `archetype-microservices-infra` already provides that annotated class. ==== +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + [source, java] ---- @Configuration @@ -189,9 +225,13 @@ The way to connect a microservice to _Eureka_ server is really simple. You only [NOTE] ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Instead of using that `@EnableMicroservices` annotation, you can use the equivalent _Spring_ annotations `@EnableDiscoveryClient` or `@EnableEurekaClient`. ==== +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + [source,java] ---- @Configuration @@ -216,6 +256,8 @@ With this the application will register automatically in _Eureka_ and will be va ==== Zuul service +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We are going to show an overview to the options of the _Zuul_ service, if you want to know more details about this particular service visit the official site of http://cloud.spring.io/spring-cloud-static/spring-cloud-netflix/1.3.0.M1/#router_and_filter_zuul[Spring Cloud]. _Zuul_ is the component in charge for router and filtering the requests to the microservices system. It works as a gateway that, through a rule engine, redirects the requests to the suitable microservice. In addition, it can be used as a security filter as it can implement PRE-Filters and POST-Filters. @@ -317,17 +359,25 @@ Having an _Eureka_ client activated, the _Zuul_ service will refresh its content ==== Security, Authentication and authorization +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The most commonly used authentication in micro-service environments is authentication based on https://jwt.io/[json web tokens], since the server does not need to store any type of user information (stateless) and therefore favors the scalability of the microservices. [IMPORTANT] ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The `service-auth` module is useful only if the authentication and authorization needs to be done by a remote service (_e.g._ to have a common auth. service to be used by several microservices). Otherwise, the autentication and authorization can happen in the main application, that will perform the authentication and will generate the JWT. ==== +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + ===== Security in the monolith application + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In this case, the main microservice or application will perform the authentication and generate the JWT, without using `service-auth`. It works as follows: @@ -344,6 +394,8 @@ image::images/microservices/microservices_07.png[,width="450", link="images/micr ===== Security in external service (`service-auth`) +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + It works as follows: - The user is authenticated in our application, either through a user / password access, or through a third provider. @@ -371,6 +423,8 @@ The `service-auth` service is already prepared to listen to the `/login` path an [NOTE] ======= + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In our example you can make a POST request to: http://localhost:8081/service-auth/services/rest/login + @@ -378,6 +432,8 @@ http://localhost:8081/service-auth/services/rest/login + {nbsp}{nbsp}{nbsp}{nbsp} BODY {nbsp}{nbsp}{nbsp}{nbsp}{nbsp}{nbsp} { "j_username" : "xxx", "j_password" : "xxx"} ======= +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This will generate a response like the following [source,json] @@ -395,6 +451,8 @@ The client now should store, in the header defined in `accessHeaderName`, the to [IMPORTANT] ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. When using `service-auth` (or any other external authorization service), we *must secure* not only the communication between the Client and Zuul, but also between Zuul and the `service-auth`. @@ -402,6 +460,8 @@ There is very sensitive information being sent (_username_ and _password_) betwe anyone could read if the channel is not properly secured. ==== +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + When configuring the `service-auth` module is very important to have into account the following aspects: - The _expiration date_ of the token can be configured in the properties file with the property `jwt.expirationTime` (will appear in minutes). @@ -453,10 +513,14 @@ image::images/microservices/microservices_06.png[,width="450", link="images/micr === How to modify the UserDetails information +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In order to modify the _UserDetails_ information we will need to accomplish two steps: modify the authentication service to generate the authentication token with the custom attributes embedded, and modify the pre-authentication filter of the microservices to convert the token into an _Object_ with the custom attributes available. ==== Modify the authentication service to generate a new token +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We must modify the `service-auth` that is in charge of logging the user and generate the security token. The first thing to do is to create a _UserDetails_ class that contains the required attributes and custom attributes. In the code sample we will call this class _UserDetailsJsonWebTokenCustomTo_, and must either implement the generic _UserDetailsJsonWebTokenAbstract_ interface or extend it from the current _UserDetailsJsonWebTokenTo_ class, since the services are prepared to work with it. In the example, we will add two new attributes `firstName` and `lastName`. @@ -557,6 +621,8 @@ Finally, in the login process the new attributes should be filled in when creati ==== Modify the pre-authentication filter to read the new token +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Once a token with custom attributes has been obtained, the steps to read it and put it in the security context are very simple. The changes shown in this point should be reproduced in those microservices where you want to use the new custom attributes. The steps to follow are those: - Create a `UserDetailsJsonWebTokenCustomTo` class that contains the new attributes, as was done in the previous section. The ideal would be to reuse the same class. @@ -578,6 +644,8 @@ With these three steps you can use the new security object with the custom attri === How to start with a microservice +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Once the microservice has been created through its archetype, you need to have a series of points in mind to configure it correctly: - The microservice must have the `microservices` starter in its `pom.xml` configuration to be able to use the interceptors and the generic configuration. @@ -614,6 +682,8 @@ The rest will be treated as if it were a normal Web application, which exposes s === Calls between microservices +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In order to invoke a microservice manually, you would need to implement the following steps: - Obtain the instances of the microservice you want to invoke. diff --git a/documentation/architecture.asciidoc b/documentation/architecture.asciidoc index 9492697d..684168d2 100644 --- a/documentation/architecture.asciidoc +++ b/documentation/architecture.asciidoc @@ -3,15 +3,15 @@ toc::[] :idprefix: :idseparator: - -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Architecture +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + There are many different views that are summarized by the term _architecture_. First, we will introduce the xref:key-principles[key principles] and xref:architecture-principles[architecture principles] of devonfw. Then, we will go into details of the the xref:application-architecture[architecture of an application]. == Key Principles + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For devonfw we follow these fundamental key principles for all decisions about architecture, design, or choosing standards, libraries, and frameworks: * *KISS* + @@ -24,6 +24,8 @@ We concentrate on providing patterns, best-practices and examples rather than wr We pick solutions that are established and have been proven to be solid and robust in real-live (business) projects. == Architecture Principles + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Additionally we define the following principles that our architecture is based on: * *Component Oriented Design* + @@ -41,6 +43,8 @@ As an architect you should be prepared for the future by reading the https://www == Application Architecture +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For the architecture of an application we distinguish the following views: * The xref:business-architecture[Business Architecture] describes an application from the business perspective. It divides the application into business components and with full abstraction of technical aspects. @@ -48,11 +52,15 @@ For the architecture of an application we distinguish the following views: * The Infrastructure Architecture describes an application from the operational infrastructure perspective. It defines the nodes used to run the application including clustering, load-balancing and networking. This view is not explored further in this guide. === Business Architecture + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The _business architecture_ divides the application into _business components_. A business component has a well-defined responsibility that it encapsulates. All aspects related to that responsibility have to be implemented within that business component. Further, the business architecture defines the dependencies between the business components. These dependencies need to be free of cycles. A business component exports its functionality via well-defined interfaces as a self-contained API. A business component may use another business component via its API and compliant with the dependencies defined by the business architecture. As the business domain and logic of an application can be totally different, the devonfw can not define a standardized business architecture. Depending on the business domain it has to be defined from scratch or from a domain reference architecture template. For very small systems it may be suitable to define just a single business component containing all the code. === Technical Architecture + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The _technical architecture_ divides the application into technical _layers_ based on the http://en.wikipedia.org/wiki/Multilayered_architecture[multilayered architecture]. A layer is a unit of code with the same category such as a service or presentation logic. So, a layer is often supported by a technical framework. Each business component can therefore be split into _component parts_ for each layer. However, a business component may not have component parts for every layer (e.g. only a presentation part that utilized logic from other components). An overview of the technical reference architecture of the devonfw is given by xref:img-t-architecture[figure "Technical Reference Architecture"]. @@ -109,6 +117,8 @@ is archived in the devonfw by the right templates and best-practices that avoid is obtained by choosing the right products and proper configurations. While the actual implementation of the application matters for performance a proper design is important as it is the key to allow performance-optimizations (see e.g. link:guide-caching.asciidoc[caching]). ==== Technology Stack + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The technology stack of the devonfw is illustrated by the following table. .Technology Stack of devonfw diff --git a/documentation/build-release-run-12factor.asciidoc b/documentation/build-release-run-12factor.asciidoc index 1c6eb9d0..c968e0a2 100644 --- a/documentation/build-release-run-12factor.asciidoc +++ b/documentation/build-release-run-12factor.asciidoc @@ -1,9 +1,7 @@ -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Build, release and run +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + *Strictly separate build and run stages* *Build*: diff --git a/documentation/coding-conventions.asciidoc b/documentation/coding-conventions.asciidoc index f56efcdd..b1d30946 100644 --- a/documentation/coding-conventions.asciidoc +++ b/documentation/coding-conventions.asciidoc @@ -1,15 +1,15 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Coding Conventions +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The code should follow general conventions for Java (see http://www.oracle.com/technetwork/java/namingconventions-139351.html[Oracle Naming Conventions], https://google.github.io/styleguide/javaguide.html[Google Java Style], etc.).We consider this as common sense and provide configurations for http://www.sonarqube.org/[SonarQube] and related tools such as http://checkstyle.sourceforge.net/[Checkstyle] instead of repeating this here. == Naming + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Besides general Java naming conventions, we follow the additional rules listed here explicitly: * Always use short but speaking names (for types, methods, fields, parameters, variables, constants, etc.). @@ -22,6 +22,8 @@ Besides general Java naming conventions, we follow the additional rules listed h * Names of Generics should be easy to understand. Where suitable follow the common rule `E=Element`, `T=Type`, `K=Key`, `V=Value` but feel free to use longer names for more specific cases such as `ID`, `DTO` or `ENTITY`. The capitalized naming helps to distinguish a generic type from a regular class. == Packages + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Java Packages are the most important element to structure your code. We use a strict packaging convention to map technical layers and business components (slices) to the code (See link:architecture.asciidoc#technical-architecture[technical architecture] for further details). By using the same names in documentation and code we create a strong link that gives orientation and makes it easy to find from business requirements, specifications or story tickets into the code and back. For an devon4j based application we use the following Java-Package schema: @@ -43,9 +45,13 @@ So in a devon4j application we could e.g. find the Spring-Data repositories for Please note that `devon4j` library modules for spring use `com.devonfw.module` as `«root»` and the name of the module as `«component»`. E.g. the API of our `beanmapping` module can be found in the package `com.devonfw.module.beanmapping.common.api`. == Code Tasks + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Code spots that need some rework can be marked with the following tasks tags. These are already properly pre-configured in your development environment for auto completion and to view tasks you are responsible for. It is important to keep the number of code tasks low. Therefore, every member of the team should be responsible for the overall code quality. So if you change a piece of code and hit a code task that you can resolve in a reliable way, please do this as part of your change and remove the according tag. === TODO + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Used to mark a piece of code that is not yet complete (typically because it can not be completed due to a dependency on something that is not ready). [source,java] @@ -54,18 +60,24 @@ Used to mark a piece of code that is not yet complete (typically because it can A TODO tag is added by the author of the code who is also responsible for completing this task. === FIXME + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. [source,java] // FIXME «author» «description» A FIXME tag is added by the author of the code or someone who found a bug he can not fix right now. The «author» who added the FIXME is also responsible for completing this task. This is very similar to a TODO but with a higher priority. FIXME tags indicate problems that should be resolved before a release is completed while TODO tags might have to stay for a longer time. === REVIEW + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. [source,java] // REVIEW «responsible» («reviewer») «description» A REVIEW tag is added by a reviewer during a code review. Here the original author of the code is responsible to resolve the REVIEW tag and the reviewer is assigning this task to him. This is important for feedback and learning and has to be aligned with a review "process" where people talk to each other and get into discussion. In smaller or local teams a peer-review is preferable but this does not scale for large or even distributed teams. == Code-Documentation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. As a general goal, the code should be easy to read and understand. Besides, clear naming the documentation is important. We follow these rules: * APIs (especially component interfaces) are properly documented with JavaDoc. @@ -76,12 +88,18 @@ As a general goal, the code should be easy to read and understand. Besides, clea * Avoid the pointless `{@inheritDoc}` as since Java 1.5 there is the `@Override` annotation for overridden methods and your JavaDoc is inherited automatically even without any JavaDoc comment at all. == Code-Style + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. This section gives you best practices to write better code and avoid pitfalls and mistakes. === BLOBs + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Avoid using `byte[]` for BLOBs as this will load them entirely into your memory. This will cause performance issues or out of memory errors. Instead, use streams when dealing with BLOBs. For further details see link:guide-blob-support.asciidoc[BLOB support]. === Daten and Time + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Avoid using `java.util.Calendar`, `java.util.Date`, `java.sql.Date`, `java.util.Timestamp`, or anything directly related. These types are historically grown, very error prone or to make it short a disaster. Stop using them now! @@ -96,6 +114,8 @@ The most important types are: When mapping types to XML, JSON, database, etc. nowadays there is support for `java.time`. === Stateless Programming + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. When implementing logic as components or _beans_ of your container using link:guide-dependency-injection.asciidoc[dependency injection], we strongly encourage stateless programming. This is not about data objects like an link:guide-jpa.asciidoc#entity[entity] or link:guide-transferobject.asciidoc[transfer-object] that are stateful by design. Instead this applies to all classes annotated with `@Named`, `@ApplicationScoped`, `@Stateless`, etc. and all their super-classes. @@ -167,6 +187,8 @@ public class UcApproveContractImpl implements UcApproveContract { ---- === Closing Resources + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Resources such as streams (`InputStream`, `OutputStream`, `Reader`, `Writer`) or transactions need to be handled properly. Therefore, it is important to follow these rules: * Each resource has to be closed properly, otherwise you will get out of file handles, TX sessions, memory leaks or the like @@ -198,6 +220,8 @@ try (InputStream in = new FileInputStream(file)) { ---- === Catching and handling Exceptions + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. When catching exceptions always ensure the following: * Never call `printStackTrace()` method on an exception @@ -207,6 +231,8 @@ When catching exceptions always ensure the following: * See link:guide-exceptions.asciidoc#handling-exceptions[exception handling] === Lambdas and Streams + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. With Java8 you have cool new features like lambdas and monads like (`Stream`, `CompletableFuture`, `Optional`, etc.). However, these new features can also be misused or led to code that is hard to read or debug. To avoid pain, we give you the following best practices: @@ -301,6 +327,8 @@ public List twitterHandles(List authors, String company) { ---- === Optionals + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. With `Optional` you can wrap values to avoid a `NullPointerException` (NPE). However, it is not a good code-style to use `Optional` for every parameter or result to express that it may be null. For such case use `@Nullable` or even better instead annotate `@NotNull` where `null` is not acceptable. However, `Optional` can be used to prevent NPEs in fluent calls (due to the lack of the elvis operator): @@ -312,6 +340,8 @@ id = Optional.ofNullable(fooCto).map(FooCto::getBar).map(BarCto::getBar).map(Bar ---- === Encoding + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Encoding (esp. Unicode with combining characters and surrogates) is a complex topic. Please study this topic if you have to deal with encodings and processing of special characters. For the basics follow these recommendations: * Whenever possible prefer unicode (UTF-8 or better) as encoding. This especially impacts your databases and has to be defined upfront as it typically can not be changed (easily) afterwards. @@ -322,6 +352,8 @@ Encoding (esp. Unicode with combining characters and surrogates) is a complex to ** Always provide an encoding when you create a `Reader` or `Writer` : `new InputStreamReader(inStream, encoding)` === Prefer general API + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Avoid unnecessary strong bindings: * Do not bind your code to implementations such as `Vector` or `ArrayList` instead of `List` @@ -330,6 +362,8 @@ Avoid unnecessary strong bindings: ** consider preferring `Collection` over `Collection` when `Foo` is an interface or super-class === Prefer primitive boolean + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Unless in rare cases where you need to allow a flag being `null` avoid using the object type `Boolean`. [source,java] ---- diff --git a/documentation/coding-tools.asciidoc b/documentation/coding-tools.asciidoc index 56a0ae3f..24fcb965 100644 --- a/documentation/coding-tools.asciidoc +++ b/documentation/coding-tools.asciidoc @@ -1,12 +1,10 @@ :toc: toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Tools +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + .Development Tools used for devon4j [options="header"] |======================= diff --git a/documentation/decision-between-Spring-and-Quarkus.asciidoc b/documentation/decision-between-Spring-and-Quarkus.asciidoc index ae128e62..15403ba9 100644 --- a/documentation/decision-between-Spring-and-Quarkus.asciidoc +++ b/documentation/decision-between-Spring-and-Quarkus.asciidoc @@ -1,15 +1,17 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Decision between Spring and Quarkus +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == Spring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Pros + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. * *highly flexible:* Spring is famous for its great flexibility. You can customize and integrate nearly everything. @@ -23,6 +25,8 @@ Spring became famous for its non-invasive coding based on patterns instead of ha === Cons +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + * *history and legacy:* Due to its long established history, spring carries a lot of legacy. As a result there are many ways to do the same thing, which can be encouraging or confusing at first. @@ -34,7 +38,11 @@ However, spring is trying to catch up with spring-native. == Quarkus +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Quarkus main information: + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Quarkus is a full-stack, Kubernetes-native Java framework made for JVMs. With its container-first-philosophy and its native compilation with GraalVM, Quarkus optimizes Java for containers with low memory usage and fast startup times. @@ -60,6 +68,8 @@ We also provide a link:quarkus/getting-started-for-spring-developers.asciidoc[gu === Pros: +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + * *fast turn-around cycles for developers:* Save changes in your Java code and immediately test the results without restarting or waiting * *faster start-up and less memory footprint:* @@ -71,6 +81,8 @@ You can find a performance comparison between Spring and Quarkus here. === Cons: +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + * *less flexible:* Quarkus is less flexible compared to spring or in other words it is more biased and coupled to specific implementations. However, the implementations just work and you have less things to choose and worry about. However, in case you want to integrate a specific or custom library you may hit limitations or lose support for native-images especially when that library is based on reflection. @@ -80,5 +92,7 @@ Therefore, check your requirements and technology stack early on when making you Since Quarkus was born in 2019 it is modern but also less established. It will be easier to get developers for spring but we already consider Quarkus mature and established enought for building production ready apps. == General Recommendation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. One essential differentiation has to be made on the decision for native or against native applications - the foreseen performance optimization of the JIT compiler of the JVM, which is not available anymore in a native image deployment. Depending on the overall landscape, it is recommended to stay with the knowledge of the available teams, e.g. continue making use of devon4j based on spring or even if already in that state, make use of Quarkus on JVM. \ No newline at end of file diff --git a/documentation/decision-service-framework.asciidoc b/documentation/decision-service-framework.asciidoc index d3a294d1..79aba2c6 100644 --- a/documentation/decision-service-framework.asciidoc +++ b/documentation/decision-service-framework.asciidoc @@ -1,21 +1,23 @@ :toc: toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Decision Sheet for Choosing a Service Framework +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We need to choose which framework(s) we want to use for building services. For the devonfw, we focus on a standard API, if available. However, we also want to recommend an implementation. While projects would still be able to choose whatever they want, we want to suggest the best, most robust, and established solution. This way, projects do not have to worry about the decision and can rely on a production-ready framework without running into any trouble. Also, besides the standard, the configuration of the implementation framework differs, so we want to give instructions in the documentation and by our sample application. This is why, in the end, the implementation also matters. If a project has a customer demand to use something else, the project has to take care of it. We will always suggest and "support" ONE solution. == REST Services +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For link:guide-rest.asciidoc[REST] services, devonfw relies on the JAX-RS standard (and NOT on spring-mvc with its proprietary annotations). https://github.com/eclipse-ee4j/jaxrs-api[JAX-RS] (Jakarta RESTful Web Services) is a Java programming language API to develop web services following the Representational State Transfer (REST) architectural pattern. For https://cxf.apache.org/[Apache CXF], the spring container was the first choice, but container abstraction has been properly introduced by design, so it can be used in JEE application servers. Apache CXF is a services framework that helps to build and develop services using frontend programming APIs, such as JAX-RS. Everything works smoothly in our sample application, and in addition, we collected feedback from various projects utilizing CXF, either with XML or JSON, with reported success in production. Therefore, we decided to use Apache CXF for Spring. For Quarkus applications, devon4j recommends to use https://github.com/resteasy/resteasy[RESTEasy], which is a JAX-RS implementation aimed at providing productivity frameworks for developing client and server RESTful applications and services in Java. == WebServices + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For WebServices we rely on the JAX-WS standard. On our short list we have https://metro.java.net[Metro2] and http://cxf.apache.org[Apache CXF]. Here a collection of facts and considerations: .Decision for JAX-WS implementation diff --git a/documentation/devon4j-doc.asciidoc b/documentation/devon4j-doc.asciidoc index b25f028e..103bad56 100644 --- a/documentation/devon4j-doc.asciidoc +++ b/documentation/devon4j-doc.asciidoc @@ -1,6 +1 @@ -include::devon4j.asciidoc[] - -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - +include::devon4j.asciidoc[] \ No newline at end of file diff --git a/documentation/devon4j.asciidoc b/documentation/devon4j.asciidoc index 1c664e94..8f74e2e9 100644 --- a/documentation/devon4j.asciidoc +++ b/documentation/devon4j.asciidoc @@ -1,9 +1,7 @@ -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Java +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + :description: comprehensive documentation for the Java stack of devonfw. :doctype: book :toc: @@ -39,6 +37,8 @@ You can also read the latest version of this documentation online at the followi * https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=com.devonfw.java.doc&a=devon4j-doc&v=LATEST&p=pdf[devon4j as PDF on maven-central] == General + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Here you will find documentation and code-patterns for developing with Java in general, independent of the framework you choose. include::architecture.asciidoc[leveloffset=+2] @@ -168,6 +168,8 @@ include::guide-structure-classic.asciidoc[leveloffset=+2] === Layers +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + include::guide-client-layer.asciidoc[leveloffset=+3] <<<< @@ -196,6 +198,8 @@ include::guide-batch-layer.asciidoc[leveloffset=+3] === Guides +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + include::spring/guide-spring-configuration.asciidoc[leveloffset=+3] include::guide-configuration-mapping.asciidoc[leveloffset=+4] @@ -288,6 +292,8 @@ include::guide-text-search.asciidoc[leveloffset=+3] === Tutorials +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + include::tutorial-newapp.asciidoc[leveloffset=+3] include::quarkus.asciidoc[leveloffset=+1] @@ -306,6 +312,8 @@ include::guide-domain-layer.asciidoc[leveloffset=+2] === Guides +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + include::quarkus/getting-started-for-spring-developers.asciidoc[leveloffset=+3] include::quarkus/guide-quarkus-configuration.asciidoc[leveloffset=+3] include::quarkus/quarkus-template.asciidoc[leveloffset=+3] diff --git a/documentation/guide-access-control-schema.asciidoc b/documentation/guide-access-control-schema.asciidoc index 88db3757..3b906cd6 100644 --- a/documentation/guide-access-control-schema.asciidoc +++ b/documentation/guide-access-control-schema.asciidoc @@ -1,15 +1,15 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Access Control Schema +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + With release `3.0.0` the `access-control-schema.xml` has been deprecated. You may still use it and find the documentation in this section. However, for new devonfw applications always start with the new approach described in link:guide-access-control#access-control-config.asciidoc[access control config]. == Legacy Access Control Schema Documentation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The file `access-control-schema.xml` is used to define the mapping from groups to permissions (see https://github.com/devonfw/my-thai-star/blob/develop/java/mtsj/core/src/main/resources/config/app/security/access-control-schema.xml[example from sample app]). The general terms discussed above can be mapped to the implementation as follows: .General security terms related to devon4j access control schema diff --git a/documentation/guide-access-control.asciidoc b/documentation/guide-access-control.asciidoc index 06ef47ae..6553206e 100644 --- a/documentation/guide-access-control.asciidoc +++ b/documentation/guide-access-control.asciidoc @@ -1,17 +1,17 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Access-Control + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Access-Control is a central and important aspect of link:guide-security.asciidoc[Security]. It consists of two major aspects: * xref:Authentication[] (Who tries to access?) * xref:Authorization[] (Is the one accessing allowed to do what he wants to do?) == Authentication + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Definition: > Authentication is the verification that somebody interacting with the system is the actual subject for whom he claims to be. @@ -21,6 +21,8 @@ The one authenticated is properly called _subject_ or http://docs.oracle.com/jav To prove the authenticity, the user provides some secret called _credentials_. The most simple form of credentials is a password. === Implementations + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. NOTE: Please never implement your own authentication mechanism or credential store. You have to be aware of implicit demands such as salting and hashing credentials, password life-cycle with recovery, expiry, and renewal including email notification confirmation tokens, central password policies, etc. This is the domain of identity and access management (IAM). There are various existing products for IAM that already solve the problems better than you could ever implement it yourselve. In a business context you will typically already find a system for this purpose that you have to integrate (e.g. via JWT and OAuth). In case you have the freedom of choice, we recommend using http://keycloak.org[keycloak]. We recommend using link:guide-jwt.asciidoc[JWT] when possible. For KISS, also try to avoid combining multiple authentication mechanisms (form based, basic-auth, SAMLv2, OAuth, etc.) within the same application (for different URLs). @@ -36,12 +38,16 @@ For link:quarkus.asciidoc[quarkus], check the link:quarkus/guide-authentication- == Authorization +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + **Definition:** > Authorization is the verification that an authenticated user is allowed to perform the operation he intends to invoke. === Clarification of terms +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For clarification we also want to give a common understanding of related terms that have no unique definition and consistent usage in the wild. .Security terms related to authorization @@ -57,6 +63,8 @@ For simple scenarios a principal has a single role associated. In more complex s |======================= === Suggestions on the access model + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For the access model we give the following suggestions: * Each Access Control (permission, group, role, ...) is uniquely identified by a human readable string. @@ -69,6 +77,8 @@ For the access model we give the following suggestions: * Technically we consider permissions as a secret of the application. Administrators shall not fiddle with individual permissions but grant them via groups. So the access management provides a list of strings identifying the Access Controls of a user. The individual application itself contains these Access Controls in a structured way, whereas each group forms a permission tree. === Naming conventions + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. As stated above each Access Control is uniquely identified by a human readable string. This string should follow the naming convention: ``` «app-id».«local-name» @@ -92,6 +102,8 @@ So as an example `shop.FindProduct` will reflect the permission to search and re === devon4j-security +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The module `devon4j-security` provides ready-to-use code based on http://projects.spring.io/spring-security/[spring-security] that makes your life a lot easier. .devon4j Security Model @@ -103,6 +115,8 @@ The diagram shows the model of `devon4j-security` that separates two different a * The application security defines a hierarchy of _secondary access control objects_ (groups and permissions). This is done by configuration owned by the application (see following section). The "API" is defined by the IDs of the primary access control objects that will be referenced from the _Identity- and Access-Management_. === Access Control Config + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In your application simply extend `AccessControlConfig` to configure your access control objects as code and reference it from your use-cases. An example config may look like this: [source,java] ---- @@ -142,6 +156,8 @@ public class ApplicationAccessControlConfig extends AccessControlConfig { ---- === Configuration on Java Method level + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In your use-case you can now reference a permission like this: [source,java] ---- @@ -156,6 +172,8 @@ public class UcSafeOfferImpl extends ApplicationUc implements UcSafeOffer { ---- === JEE Standard + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. https://en.wikipedia.org/wiki/Role-based_access_control[Role-based Access Control (RBAC)] is commonly used for authorization. JSR 250 defines a number of common annotations to secure your application. @@ -193,6 +211,8 @@ This class is typically called `ApplicationAccessControlConfig` in devonfw. In many complicated cases where `@PermitAll` `@DenyAll` `@RolesAllowed` are insufficient e.g. a method should be accessed by a user in role A and not in role B at the same time, you have to verify the user role directly in the method. You can use `SecurityContext` class to get further needed information. ==== Spring + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Spring Security also supports authorization on method level. To use it, you need to add the `spring-security-config` dependency. If you use Spring Boot, the dependency `spring-boot-starter-security` already includes `spring-security-config`. Then you can configure as follows: * `prePostEnabled` property enables Spring Security pre/post annotations. `@PreAuthorize` and `@PostAuthorize` annotations provide expression-based access control. See more https://docs.spring.io/spring-security/site/docs/4.2.x/reference/html/el-access.html[here] @@ -213,10 +233,16 @@ public class MethodSecurityConfig A further read about the whole concept of Spring Security Authorization can be found https://docs.spring.io/spring-security/site/docs/current/reference/html5/#servlet-authorization[here]. ==== Quarkus + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Quarkus comes with built-in security to allow for RBAC based on the common security annotations `@RolesAllowed`, `@DenyAll`, `@PermitAll` on REST endpoints and CDI beans. Quarkus also provides the `io.quarkus.security.Authenticated` annotation that will permit any authenticated user to access the resource (equivalent to @RolesAllowed("**")). === Data-based Permissions + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. See link:guide-data-permission.asciidoc[data permissions] === Access Control Schema (deprecated) + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The `access-control-schema.xml` approach is deprecated. The documentation can still be found in link:guide-access-control-schema.asciidoc[access control schema]. diff --git a/documentation/guide-accessibility.asciidoc b/documentation/guide-accessibility.asciidoc index f34dd331..b2376f8d 100644 --- a/documentation/guide-accessibility.asciidoc +++ b/documentation/guide-accessibility.asciidoc @@ -1,12 +1,10 @@ :toc: toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Accessibility +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + TODO http://www.w3.org/TR/WCAG20/ diff --git a/documentation/guide-aop.asciidoc b/documentation/guide-aop.asciidoc index e977eb3e..7baa65de 100644 --- a/documentation/guide-aop.asciidoc +++ b/documentation/guide-aop.asciidoc @@ -1,15 +1,15 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Aspect Oriented Programming (AOP) +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + http://en.wikipedia.org/wiki/Aspect-oriented_programming[AOP] is a powerful feature for cross-cutting concerns. However, if used extensive and for the wrong things an application can get unmaintainable. Therefore we give you the best practices where and how to use AOP properly. == AOP Key Principles + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We follow these principles: * We use http://docs.spring.io/spring/docs/2.5.4/reference/aop.html[spring AOP] based on dynamic proxies (and fallback to cglib). @@ -17,6 +17,8 @@ We follow these principles: * We only use AOP where we consider it as necessary (see below). == AOP Usage + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We recommend to use AOP with care but we consider it established for the following cross cutting concerns: * link:guide-transactions.asciidoc[Transaction-Handling] @@ -26,6 +28,8 @@ We recommend to use AOP with care but we consider it established for the followi * Exception facades for link:guide-service-layer.asciidoc[services] but only if no other solution is possible (use alternatives such as link:guide-service-layer.asciidoc#rest-exception-handling[JAX-RS provider] instead). == AOP Debugging + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. //Exchange picture with one of the current version? When using AOP with dynamic proxies the debugging of your code can get nasty. As you can see by the red boxes in the call stack in the debugger there is a lot of magic happening while you often just want to step directly into the implementation skipping all the AOP clutter. When using Eclipse this can easily be archived by enabling _step filters_. Therefore you have to enable the feature in the Eclipse tool bar (highlighted in read). diff --git a/documentation/guide-api-first.asciidoc b/documentation/guide-api-first.asciidoc index d1cfef95..ec617046 100644 --- a/documentation/guide-api-first.asciidoc +++ b/documentation/guide-api-first.asciidoc @@ -1,16 +1,16 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = API first development guide +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Cloud native promotes the use of microservices, which are loosely coupled and self-contained. These services communicate with each other using a well-defined interface or API, and no consumer needs to be aware of any implementation details of the provider. There could even be multiple providers of the same API, or we can decide to swap existing implementation for a new one, without disrupting our clients - all because we adhere to a well defined API. This guide focuses on HTTP interfaces following RESTful design principles. == API first strategy + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. API first strategy treats APIs as first class citizens in the delivery model. The APIs are modeled/designed first (usually as link:guide-openapi.asciidoc[OpenAPI specification]), often in a collaborative process between providers and consumers, and only once the APIs are defined do we start with development of the provider service. This requires a bit more time upfront, but also provides opportunity to think about the behaviour of the system before it gets implemented. Several other advatages of this approach: @@ -20,6 +20,8 @@ This requires a bit more time upfront, but also provides opportunity to think ab == API first provider +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + After careful planning, we defined our future API. Now we would like to implement a provider of this API. We could manually create all the link:guide-rest.asciidoc#jax-rs[JAX-RS] endpoints based on the schema and then test whether the actually provided interface conforms with the API schema. However, it is an error prone and laborious process, especially if the API gets big. Luckily, we can use great open source tooling to generate JAX-RS interfaces that conform to 100% with the schema, and then we simply implement them. @@ -28,6 +30,8 @@ There are many open source tools, that allow code generation from OpenAPI schema === OpenAPI Generator maven plugin +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + If we already have our backend maven project, using the maven plugin will be easiest for us. Lets define a new maven profile and add the OpenAPI generator plugin: [source, xml] ---- @@ -93,6 +97,8 @@ The OpenAPI generator has many more configuration options that are outside the s === Generate once vs generate always +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Depending on our needs, we may either want to generate the interfaces and models once and afterwards copy them to our project as general source code files, or treat them as immutable generated assets, that we generate anew with every build. Both scenarios have their pros and cons, and you'll need to find out what best suits your project. In the example above, we use a profile with `activeByDefault=true`, which will cause the generator to run with every build. The generated files will be included as sources in our project, so we can import them in any other java class without issues. @@ -100,6 +106,8 @@ In case you only want to generate your API resources once and version them after === Implement the generated interfaces +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To implement the generated interfaces, we simply create an impl class - rest controller bean - that implements the interface from our `gen` package: [source, java] @@ -138,6 +146,8 @@ And now we can invoke our API endpoint as usual: `http://localhost:8080/pets` - === Serving API docs / Swagger-UI +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + A common requirement is that our backend API provider should also provide an endpoint with the schema or a Swagger-UI application with that schema. In our example, we decided to generate the JAX-RS interface without Swagger/OpenAPI annotations, therefore the schema can not be re-constructed 1:1 from our code (missing method documentation, error handling, etc.). @@ -145,4 +155,6 @@ When having a Quarkus application and using the link:guide-openapi.asciidoc#smal === Advanced topics +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In some cases, we may have specific requirements or API extensions that are not supported by the existing generators. OpenAPI generator project allows us to define https://github.com/OpenAPITools/openapi-generator/tree/master/modules/openapi-generator-maven-plugin#custom-generator[custom genererator], or to extend the existing https://openapi-generator.tech/docs/templating[generator templates]. We can also selectively generate subset of the models or API endpoints, generate test code and much more. diff --git a/documentation/guide-apm.asciidoc b/documentation/guide-apm.asciidoc index 074358bb..7f683586 100644 --- a/documentation/guide-apm.asciidoc +++ b/documentation/guide-apm.asciidoc @@ -1,25 +1,31 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Application Performance Management +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This guide gives hints how to manage, monitor and analyse performance of Java applications. == Temporary Analysis + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. If you are facing performance issues and want to do a punctual analysis we recommend you to use https://glowroot.org/[glowroot]. It is ideal in cases where monitoring in your local development environment is suitable. However, it is also possible to use it in your test environment. It is entirely free and open-source. Still it is very powerful and helps to trace down bottlenecks. To get a first impression of the tool take a look at the https://demo.glowroot.org[demo]. === JEE/WTP + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In case you are forced to use an link:guide-jee.asciidoc[JEE application server] and want to do a temporary analysis you can double click your server instance from the servers view in Eclipse and click on the link `Open launch configuration` in order to add the `-javaagent` JVM option. == Regular Analysis + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In case you want to manage application performance regularly we recommend to use https://github.com/javamelody/javamelody#javamelody[JavaMelody] that can be integrated into your application. More information on javamelody is available on the https://github.com/javamelody/javamelody/wiki[JavaMelody Wiki] == Alternatives +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + * https://github.com/naver/pinpoint[PinPoint] * https://openapm.io/[OpenAPM] * https://www.appdynamics.com/java/[AppDynamics] diff --git a/documentation/guide-auditing.asciidoc b/documentation/guide-auditing.asciidoc index 3ea00a5a..67ded103 100644 --- a/documentation/guide-auditing.asciidoc +++ b/documentation/guide-auditing.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Auditing +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For database auditing we use http://envers.jboss.org/[hibernate envers]. If you want to use auditing ensure you have the following dependency in your +pom.xml+: .**spring** diff --git a/documentation/guide-batch-layer.asciidoc b/documentation/guide-batch-layer.asciidoc index 311cd561..3289770f 100644 --- a/documentation/guide-batch-layer.asciidoc +++ b/documentation/guide-batch-layer.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Batch Layer +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We understand batch processing as a bulk-oriented, non-interactive, typically long running execution of tasks. For simplicity, we use the term "batch" or "batch job" for such tasks in the following documentation. devonfw uses link:http://projects.spring.io/spring-batch/[Spring Batch] as a batch framework. @@ -20,6 +18,8 @@ In this chapter, we will describe the overall architecture (especially concernin == Layering +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Batches are implemented in the batch layer. The batch layer is responsible for batch processes, whereas the business logic is implemented in the logic layer. Compared to the link:guide-service-layer.asciidoc[service layer], you may understand the batch layer just as a different way of accessing the business logic. From a component point of view, each batch is implemented as a subcomponent in the corresponding business component. The business component is defined by the link:architecture.asciidoc[business architecture]. @@ -34,13 +34,19 @@ Batches should invoke use cases in the logic layer for doing their work. Only "batch specific" technical aspects should be implemented in the batch layer. ========================== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Example: For a batch, which imports product data from a CSV file, this means that all code for actually reading and parsing the CSV input file is implemented in the batch layer. The batch calls the use case "create product" in the logic layer for actually creating the products for each line read from the CSV input file. ========================== +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Directly accessing data access layer + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In practice, it is not always appropriate to create use cases for every bit of work a batch should do. Instead, the data access layer can be used directly. An example for that is a typical batch for data retention which deletes out-of-time data. Often deleting, out-dated data is done by invoking a single SQL statement. It is appropriate to implement that SQL in a link:guide-repository.asciidoc[Repository] or link:guide-dao.asciidoc[DAO] method and call this method directly from the batch. @@ -49,6 +55,8 @@ It is a typical design decision you have to make when designing your specific ba == Project structure and packaging +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Batches will be implemented in a separate Maven module to keep the application core free of batch dependencies. The batch module includes a dependency on the application core-module to allow the reuse of the use cases, DAOs etc. Additionally the batch module has dependencies on the required spring batch jars: @@ -115,12 +123,16 @@ To allow an easy xref:start-batch[start of the batches] from the command line it == Implementation +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Most of the details about implementation of batches is described in the https://spring.io/projects/spring-batch[spring batch documentation]. There is nothing special about implementing batches in devonfw. You will find an easy https://github.com/devonfw/my-thai-star/tree/develop/java/mtsj/batch[example in my-thai-star]. [[start-batch]] == Starting from command line +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Devonfw advises to start batches via command line. This is most common to many ops teams and allows easy integration in existing xref:scheduling[schedulers]. In general batches are started with the following command: ---- @@ -140,6 +152,8 @@ This will launch your normal spring boot app, disables the web application part [scheduling] == Scheduling +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In real world scheduling of batches is not as simple as it first might look like. * Multiple batches have to be executed in order to achieve complex tasks. If one of those batches fails the further execution has to be stopped and operations should be notified for example. @@ -154,6 +168,8 @@ This gives full control to operations to choose the solution which fits best int == Handling restarts +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + If you start a job with the same parameters set after a failed run (BatchStatus.FAILED) a restart will occur. In many cases your batch should then not reprocess all items it processed in the previous runs. For that you need some logic to start at the desired offset. There different ways to implement such logic: @@ -164,12 +180,16 @@ For that you need some logic to start at the desired offset. There different way === Using spring batch ExecutionContext for restarts +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + By implementing the `ItemStream` interface in your `ItemReader` or `ItemWriter` you may store information about the batch progress in the `ExecutionContext`. You will find an example for that in the CountJob in My Thai Star. Additional hint: It is important that bean definition method of your `ItemReader`/`ItemWriter` return types implementing `ItemStream`(and not just `ItemReader` or `ItemWriter` alone). For that the `ItemStreamReader` and `ItemStreamWriter` interfaces are provided. == Exit codes +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Your batches should create a meaningful exit code to allow reaction to batch errors e.g. in a xref:scheduling[scheduler]. For that spring batch automatically registers an `org.springframework.boot.autoconfigure.batch.JobExecutionExitCodeGenerator`. To make this mechanism work your spring boot app main class as to populate this exit code to the JVM: @@ -193,6 +213,8 @@ public class SpringBootApp { == Stop batches and manage batch status +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Spring batch uses several database tables to store the status of batch executions. Each execution may have link:https://docs.spring.io/spring-batch/docs/current/reference/html/index-single.html#jobexecution[different status]. You may use this mechanism to link:https://docs.spring.io/spring-batch/docs/current/reference/html/index-single.html#stoppingAJob[gracefully stop batches]. @@ -201,6 +223,8 @@ E.g. the state will be running, despite the process crashed sometime ago. For that cases you have to change the status of the execution in the database. === CLI-Tool + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Devonfw provides a easy to use cli-tool to manage the executing status of your jobs. The tool is implemented in the devonfw module `devon4j-batch-tool`. It will provide a runnable jar, which may be used as follows: @@ -218,6 +242,8 @@ This means that you have to make sure that the corresponding DB driver is in the == Authentication +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Most business application incorporate authentication and authorization. Your spring boot application will implement some kind of security, e.g. integrated login with username+password or in many cases authentication via an existing IAM. For security reasons your batch should also implement an authentication mechanism and obey the authorization implemented in your application (e.g. via @RolesAllowed). @@ -280,6 +306,10 @@ public class BookingsExportBatchConfig { == Tipps & tricks +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Identifying job parameters +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Spring uses a jobs parameters to identify https://docs.spring.io/spring-batch/docs/current/reference/html/domain.html#jobexecution[job executions]. Parameters starting with "-" are not considered for identifying a job execution. diff --git a/documentation/guide-beanmapping.asciidoc b/documentation/guide-beanmapping.asciidoc index 91ac1a9d..a696a5da 100644 --- a/documentation/guide-beanmapping.asciidoc +++ b/documentation/guide-beanmapping.asciidoc @@ -1,14 +1,10 @@ :toc: macro toc::[] //Replaced old person examples with new User example - - -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Bean-Mapping +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For decoupling, you sometimes need to create separate objects (beans) for a different view. E.g. for an external service, you will use a link:guide-transferobject.asciidoc[transfer-object] instead of the link:guide-jpa.asciidoc#entity[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 what creates a copy. This also has the benefit that modifications to the copy have no side-effect on the original source object. However, to implement such mapping code by hand is very tedious and error-prone (if new properties are added to beans but not to mapping code): diff --git a/documentation/guide-blob-support.asciidoc b/documentation/guide-blob-support.asciidoc index 95ca4200..96e17c5d 100644 --- a/documentation/guide-blob-support.asciidoc +++ b/documentation/guide-blob-support.asciidoc @@ -1,18 +1,16 @@ :toc: macro toc::[] - - -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = BLOB support +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + BLOB stands for **B**inary **L**arge **Ob**ject. A BLOB may be an image, an office document, ZIP archive or any other multimedia object. Often these BLOBs are large. if this is the case you need to take care, that you do not copy all the blob data into you application heap, e.g. when providing them via a REST service. This could easily lead to performance problems or out of memory errors. As solution for that problem is "streaming" those BLOBs directly from the database to the client. To demonstrate how this can be accomplished, devonfw provides a link:https://github.com/devonfw-sample/devon4j-blob-streaming[example]. == Further Reading + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - link:guide-jpa.asciidoc#blob[BLOBs and the Data Access Layer] - https://www.owasp.org/index.php/Unrestricted_File_Upload[Security Vulnerability Unrestricted File Upload] diff --git a/documentation/guide-caching.asciidoc b/documentation/guide-caching.asciidoc index de1b1d2e..fb114d46 100644 --- a/documentation/guide-caching.asciidoc +++ b/documentation/guide-caching.asciidoc @@ -1,11 +1,9 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Caching + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. //Maybe finish the guide? Caching is a technical approach to improve performance. While it may appear easy on the first sight it is an advanced topic. In general, try to use caching only when required for performance reasons. If you come to the point that you need caching first think about: @@ -18,12 +16,20 @@ Is a local cache sufficient or do you need a shared cache? == Local Cache +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == Shared Cache +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Distributed Cache +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == Products +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + * http://ehcache.org/ * http://hazelcast.org/ * http://terracotta.org/ @@ -31,6 +37,8 @@ Is a local cache sufficient or do you need a shared cache? == Caching of Web-Resources +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + * http://www.mobify.com/blog/beginners-guide-to-http-cache-headers/ * http://en.wikipedia.org/wiki/Web_cache#Cache_control * http://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Avoiding_caching \ No newline at end of file diff --git a/documentation/guide-client-layer.asciidoc b/documentation/guide-client-layer.asciidoc index b453d64d..c569a3d8 100644 --- a/documentation/guide-client-layer.asciidoc +++ b/documentation/guide-client-layer.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Client Layer +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + There are various technical approaches to building GUI clients. The devonfw proposes rich clients that connect to the server via data-oriented services (e.g. using REST with JSON). In general, we have to distinguish among the following types of clients: @@ -18,6 +16,8 @@ Our main focus is on web-clients. In our sample application https://github.com/d == JavaScript for Java Developers +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In order to get started with client development as a Java developer we give you some hints to get started. Also if you are an experienced JavaScript developer and want to learn Java this can be helpful. First, you need to understand that the JavaScript ecosystem is as large as the Java ecosystem and developing a modern web client requires a lot of knowledge. The following table helps you as experienced developer to get an overview of the tools, configuration-files, and other related aspects from the new world to learn. Also it helps you to map concepts between the ecosystems. Please note that we list the tools recommended by devonfw here (and we know that there are alternatives not listed here such as gradle, grunt, bower, etc.). .Aspects in JavaScript and Java ecosystem diff --git a/documentation/guide-common.asciidoc b/documentation/guide-common.asciidoc index 9c0f70b6..296f2e76 100644 --- a/documentation/guide-common.asciidoc +++ b/documentation/guide-common.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Common +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In our link:coding-conventions.asciidoc[coding-conventions] we define a clear link:coding-conventions.asciidoc#packages[packaging] and link:coding-conventions.asciidoc#layers[layering]. However, there is always cross-cutting code that does not belong to a specific layer such as generic helpers, general code for configuration or integration, etc. Therefore, we define a package segment `common` that can be used as `«layer»` for such cross-cutting code. diff --git a/documentation/guide-component-facade.asciidoc b/documentation/guide-component-facade.asciidoc index 959c73fa..9c38d120 100644 --- a/documentation/guide-component-facade.asciidoc +++ b/documentation/guide-component-facade.asciidoc @@ -1,11 +1,9 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Component Facade + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. [NOTE] Our recommended approach for implementing the logic layer is link:guide-usecase.asciidoc[use-cases] @@ -14,6 +12,8 @@ This is an interface defining all business operations of the component. It carries the name of the component (`«Component»`) and has an implementation named `«Component»Impl` (see xref:implementation[implementation]). == API + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The component facade interface defines the logic API of the component and has to be business oriented. This means that all parameters and return types of all methods from this API have to be business link:guide-transferobject.asciidoc[transfer-objects], link:guide-datatype.asciidoc[datatypes] (`String`, `Integer`, `MyCustomerNumber`, etc.), or collections of these. The API may also only access objects of other business components listed in the (transitive) dependencies of the link:architecture.asciidoc#business-architecture[business-architecture]. @@ -35,6 +35,8 @@ public interface Bookingmanagement { ---- == Implementation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The implementation of an interface from the link:guide-logic-layer.asciidoc[logic layer] (a component facade or a link:guide-usecase.asciidoc[use-case]) carries the name of that interface with the suffix `Impl` and is annotated with `@Named`. An implementation typically needs access to the persistent data. This is done by link:guide-dependency-injection.asciidoc[injecting] the corresponding link:guide-repository.asciidoc[repository] (or link:guide-dao.asciidoc[DAO]). diff --git a/documentation/guide-component.asciidoc b/documentation/guide-component.asciidoc index 9454463d..d0a32e66 100644 --- a/documentation/guide-component.asciidoc +++ b/documentation/guide-component.asciidoc @@ -1,21 +1,23 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Components +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Following link:architecture.asciidoc#architecture-principles[separation-of-concerns] we divide an application into components using our link:coding-conventions.asciidoc#packages[package-conventions] and link:guide-structure.asciidoc[project structure]. As described by the link:architecture.asciidoc[architecture] each component is divided into layers as described in the link:guide-structure.asciidoc[project structure]. Please note that a component will only have the required layers. So a component may have any number from one to all layers. == General Component + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Cross-cutting aspects belong to the implicit component `general`. It contains technical configurations and very general code that is not business specific. Such code shall not have any dependencies to other components and therefore business related code. == Business Component + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The link:architecture.asciidoc#business-architecture[business-architecture] defines the business components with their allowed dependencies. A small application (microservice) may just have one component and no dependencies making it simple while the same architecture can scale up to large and complex applications (from bigger microservice up to modulith). Tailoring an business domain into applications and applications into components is a tricky task that needs the skills of an experienced architect. Also, the tailoring should follow the business and not split by technical reasons or only by size. @@ -24,12 +26,16 @@ Whatever hypes like microservices are telling you, never get misled in this rega If your system grows and reaches `MAX+1` lines of code, it is not the right motivation to split it into two microservices of `~MAX/2` lines of code - such approaches will waste huge amounts of money and lead to chaos. == App Component + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Only in case you need cross-cutting code that aggregates another component you may introduce the component `app`. It is allowed to depend on all other components but no other component may depend on it. With the modularity and flexibility of spring you typically do not need this. However, when you need to have a class that registers all services or component-facades using direct code dependencies, you can introduce this component. == Component Example + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The following class diagram illustrates an example of the business component `Staffmanagement`: image::images/guide-logic-layer.png["logic layer component pattern",scaledwidth="80%",align="center"] diff --git a/documentation/guide-configuration-mapping.asciidoc b/documentation/guide-configuration-mapping.asciidoc index 2d590215..dc57a49b 100644 --- a/documentation/guide-configuration-mapping.asciidoc +++ b/documentation/guide-configuration-mapping.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Mapping configuration to your code +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + If you are using `spring-boot` as suggested by `devon4j` your application can be configured by `application.properties` file as described in link:guide-configuration.asciidoc[configuration]. To get a single configuration option into your code for flexibility, you can use @@ -24,6 +22,8 @@ You may even use `@Value("${my.property.name:my-default-value}")` to make the pr == Naming conventions for configuration properties +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + As a best practice your configruation properties should follow these naming conventions: * build the property-name as a path of segments separated by the dot character (`.`) @@ -34,6 +34,8 @@ As a best practice your configruation properties should follow these naming conv == Mapping advanced configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + However, in many scenarios you will have features that require more than just one property. Injecting those via `@Value` is not leading to good code quality. Instead we create a class with the suffix `ConfigProperties` containing all configuration properties for our aspect that is annotated with `@ConfigurationProperties`: @@ -92,6 +94,8 @@ For further details about this feature also consult https://www.baeldung.com/con == Generate configuration metadata +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + You should further add this `dependency` to your module containing the `*ConfigProperties`: ```xml diff --git a/documentation/guide-configuration.asciidoc b/documentation/guide-configuration.asciidoc index cb3cb3d7..70c83eca 100644 --- a/documentation/guide-configuration.asciidoc +++ b/documentation/guide-configuration.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + An application needs to be configurable in order to allow internal setup (like CDI) but also to allow externalized configuration of a deployed package (e.g. integration into runtime environment). We rely on a comprehensive configuration approach following a "convention over configuration" pattern. This guide adds on to this by detailed instructions and best-practices how to deal with configurations. In general we distinguish the following kinds of configuration that are explained in the following sections: @@ -16,16 +14,22 @@ In general we distinguish the following kinds of configuration that are explaine * xref:business-configuration[Externalized Business configuration] maintained by business administrators == Internal Application Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The application configuration contains all internal settings and wirings of the application (bean wiring, database mappings, etc.) and is maintained by the application developers at development time. For more detail of link:spring.asciidoc[Spring] stack, see link:spring/guide-spring-configuration.asciidoc#internal-application-configuration[here] == Externalized Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Externalized configuration is a configuration that is provided separately to a deployment package and can be maintained undisturbed by re-deployments. === Environment Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The environment configuration contains configuration parameters (typically port numbers, host names, passwords, logins, timeouts, certificates, etc.) specific for the different environments. These are under the control of the operators responsible for the application. The environment configuration is maintained in `application.properties` files, defining various properties. @@ -42,6 +46,8 @@ More about structuring your `application.properties` files can be read link:spri For Quarkus, please refer to https://quarkus.io/guides/config-reference[Quarkus Config Reference] for more details. === Business Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Often applications do not need business configuration. In case they do it should typically be editable by administrators via the GUI. The business configuration values should therefore be stored in the database in key/value pairs. Therefore we suggest to create a dedicated table with (at least) the following columns: @@ -60,9 +66,13 @@ We recommend the following base layout for the hierarchical business configurati == Security + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Often you need to have passwords (for databases, third-party services, etc.) as part of your configuration. These are typically environment specific (see above). However, with DevOps and continuous-deployment you might be tempted to commit such configurations into your version-control (e.g. `git`). Doing that with plain text passwords is a severe problem especially for production systems. Never do that! Instead we offer some suggestions how to deal with sensible configurations: === Password Encryption + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A simple but reasonable approach is to configure the passwords encrypted with a master-password. The master-password should be a strong secret that is specific for each environment. It must never be committed to version-control. For link:spring.asciidoc[Spring], we use https://github.com/ulisesbocchio/jasypt-spring-boot#jasypt-spring-boot[jasypt-spring-boot]. For more details, see link:spring/guide-spring-configuration.asciidoc#password-encryption[here] @@ -71,5 +81,7 @@ For link:quarkus.asciidoc[Quarkus], see link:quarkus/guide-quarkus-configuration ==== Is this Security by Obscurity? +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + * Yes, from the point of view to protect the passwords on the target environment this is nothing but security by obscurity. If an attacker somehow got full access to the machine this will only cause him to spend some more time. * No, if someone only gets the configuration file. So all your developers might have access to the version-control where the config is stored. Others might have access to the software releases that include this configs. But without the master-password that should only be known to specific operators none else can decrypt the password (except with brute-force what will take a very long time, see jasypt for details). diff --git a/documentation/guide-cors-support.asciidoc b/documentation/guide-cors-support.asciidoc index e1fb2ef0..ade6d1b2 100644 --- a/documentation/guide-cors-support.asciidoc +++ b/documentation/guide-cors-support.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = CORS support +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + When you are developing Javascript client and server application separately, you have to deal with cross domain issues. We have to request from a origin domain distinct to target domain and browser does not allow this. So , we need to prepare server side to accept request from other domains. We need to cover the following points: @@ -23,8 +21,12 @@ For more information about CORS see https://developer.mozilla.org/en-US/docs/Web == Configuring CORS support +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To enable CORS support for your application, see the advanced guides. For Spring applications see link:spring/guide-cors-spring.asciidoc[here]. For Quarkus follow the https://quarkus.io/guides/http-reference#cors-filter[official Quarkus guide]. == Configuration with service mesh +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + If you are using a service mesh, you can also define your CORS policy directly there. Here is an example from https://istio.io/latest/docs/reference/config/networking/virtual-service/#CorsPolicy[Istio]. diff --git a/documentation/guide-csrf.asciidoc b/documentation/guide-csrf.asciidoc index 8a4f1c6e..75741b02 100644 --- a/documentation/guide-csrf.asciidoc +++ b/documentation/guide-csrf.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Cross-site request forgery (CSRF) +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + CSRF is a type of malicious exploit of a web application that allows an attacker to induce users to perform actions that they do not intend to perform. image::images/csrf.png[,width="450", link="images/jwt_flow.png"] @@ -15,12 +13,16 @@ More details about csrf can be found at https://owasp.org/www-community/attacks/ == Secure devon4j server against CSRF +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In case your devon4j server application is not accessed by browsers or the web-client is using link:guide-jwt.asciidoc[JWT based authentication], you are already safe according to CSRF. However, if your application is accessed from a browser and you are using _form based authentication_ (with session coockie) or _basic authentication_, you need to enable CSRF protection. This guide will tell you how to do this. === Dependency +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To secure your devon4j application against CSRF attacks, you only need to add the following dependency: [source,xml] @@ -36,6 +38,8 @@ However, if you have started from an older version or you want to understand mor === Pluggable web-security +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To enable pluggable security via devon4j security starters you need to apply `WebSecurityConfigurer` to your `BaseWebSecurityConfig` (your class extending spring-boot's `WebSecurityConfigurerAdapter`) as following: [source,java] @@ -54,6 +58,8 @@ To enable pluggable security via devon4j security starters you need to apply `We === Custom CsrfRequestMatcher +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + If you want to customize which HTTP requests will require a CSRF token, you can implement your own `CsrfRequestMatcher` and provide it to the devon4j CSRF protection via qualified injection as following: [source,java] @@ -71,6 +77,8 @@ Please note that the exact name (`@Named("CsrfRequestMatcher")`) is required her === CsrfRestService +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + With the `devon4j-starter-security-csrf` the `CsrfRestService` gets integrated into your app. It provides an operation to get the CSRF token via an HTTP `GET` request. The URL path to retrieve this CSRF token is `services/rest/csrf/v1/token`. @@ -90,6 +98,8 @@ It has to be send with subsequent HTTP requests (when method is other than `GET` === How it works +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Putting it all together, a browser client should call the `CsrfRestService` after successfull login to receive the current CSRF token. With every subsequent HTTP request (other than `GET`) the client has to send this token in the according HTTP header. Otherwise the server will reject the request to prevent CSRF attacks. @@ -101,4 +111,6 @@ This way your application will be secured against CSRF attacks. == Configure devon4ng client for CSRF +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Devon4ng client configuration for CSRF is described link:https://github.com/devonfw/devon4ng/blob/develop/documentation/guide-consuming-rest-services.asciidoc[here] diff --git a/documentation/guide-dao.asciidoc b/documentation/guide-dao.asciidoc index e4cfc995..7a149c83 100644 --- a/documentation/guide-dao.asciidoc +++ b/documentation/guide-dao.asciidoc @@ -1,18 +1,18 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Data Access Object +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The _Data Access Objects_ (DAOs) are part of the persistence layer. They are responsible for a specific xref:entity[entity] and should be named `«Entity»Dao` and `«Entity»DaoImpl`. The DAO offers the so called CRUD-functionalities (create, retrieve, update, delete) for the corresponding entity. Additionally a DAO may offer advanced operations such as link:guide-jpa-query.asciidoc[query] or locking methods. == DAO Interface + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For each DAO there is an interface named `«Entity»Dao` that defines the API. For CRUD support and common naming we derive it from the `ApplicationDao` interface that comes with the devon application template: [source,java] ---- @@ -23,6 +23,8 @@ public interface MyEntityDao extends ApplicationDao { All CRUD operations are inherited from `ApplicationDao` so you only have to declare the additional methods. == DAO Implementation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Implementing a DAO is quite simple. We create a class named `«Entity»DaoImpl` that extends `ApplicationDaoImpl` and implements your `«Entity»Dao` interface: [source,java] ---- @@ -40,6 +42,8 @@ Again you only need to implement the additional non-CRUD methods that you have d In the DAO implementation you can use the method `getEntityManager()` to access the `EntityManager` from the JPA. You will need the `EntityManager` to create and execute link:guide-jpa-query.asciidoc[queries]. === Static queries for DAO Implementation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. All static link:guide-jpa-query.asciidoc[queries] are declared in the file `src\main\resources\META-INF\orm.xml`: [source,xml] ---- diff --git a/documentation/guide-data-permission.asciidoc b/documentation/guide-data-permission.asciidoc index bb4691de..d132e333 100644 --- a/documentation/guide-data-permission.asciidoc +++ b/documentation/guide-data-permission.asciidoc @@ -1,15 +1,15 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Data-permissions +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In some projects there are demands for permissions and authorization that is dependent on the processed data. E.g. a user may only be allowed to read or write data for a specific region. This is adding some additional complexity to your authorization. If you can avoid this it is always best to keep things simple. However, in various cases this is a requirement. Therefore the following sections give you guidance and patterns how to solve this properly. == Structuring your data + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For all your business objects (entities) that have to be secured regarding to data permissions we recommend that you create a separate interface that provides access to the relevant data required to decide about the permission. Here is a simple example: [source,java] ---- @@ -26,6 +26,8 @@ public interface SecurityDataPermissionCountry { Now related business objects (entities) can implement this interface. Often such data-permissions have to be applied to an entire object-hierarchy. For security reasons we recommend that also all child-objects implement this interface. For performance reasons we recommend that the child-objects redundantly store the data-permission properties (such as `country` in the example above) and this gets simply propagated from the parent, when a child object is created. == Permissions for processing data + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. When saving or processing objects with a data-permission, we recommend to provide dedicated methods to verify the permission in an abstract base-class such as `AbstractUc` and simply call this explicitly from your business code. This makes it easy to understand and debug the code. Here is a simple example: [source,java] ---- @@ -33,6 +35,8 @@ protected void verifyPermission(SecurityDataPermissionCountry entity) throws Acc ---- === Beware of AOP + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For simple but cross-cutting data-permissions you may also use link:guide-aop.asciidoc[AOP]. This leads to programming aspects that reflectively scan method arguments and magically decide what to do. Be aware that this quickly gets tricky: * What if multiple of your method arguments have data-permissions (e.g. implement `SecurityDataPermission*`)? @@ -42,6 +46,8 @@ For simple but cross-cutting data-permissions you may also use link:guide-aop.as What we have learned is that annotations like `@PreAuthorize` from `spring-security` easily lead to the "programming in string literals" anti-pattern. We strongly discourage to use this anti-pattern. In such case writing your own `verifyPermission` methods that you manually call in the right places of your business-logic is much better to understand, debug and maintain. == Permissions for reading data + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. When it comes to restrictions on the data to read it becomes even more tricky. In the context of a user only entities shall be loaded from the database he is permitted to read. This is simple for loading a single entity (e.g. by its ID) as you can load it and then if not permitted throw an exception to secure your code. But what if the user is performing a search query to find many entities? For performance reasons we should only find data the user is permitted to read and filter all the rest already via the database query. But what if this is not a requirement for a single query but needs to be applied cross-cutting to tons of queries? Therefore we have the following pattern that solves your problem: For each data-permission attribute (or set of such) we create an abstract base entity: @@ -168,6 +174,8 @@ public class PermissionCheckerAdvisor implements PointcutAdvisor, Pointcut, Clas } ---- == Managing and granting the data-permissions + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Following our link:guide-access-control.asciidoc#authorization[authorization guide] we can simply create a permission for each country. We might simply reserve a prefix (as virtual `«app-id»`) for each data-permission to allow granting data-permissions to end-users across all applications of the IT landscape. In our example we could create access controls `country.DE`, `country.US`, `country.ES`, etc. and assign those to the users. The method `permissionChecker.getPermittedCountriesForReading()` would then scan for these access controls and only return the 2-letter country code from it. CAUTION: Before you make your decisions how to design your access controls please clarify the following questions: diff --git a/documentation/guide-dataaccess-layer.asciidoc b/documentation/guide-dataaccess-layer.asciidoc index 1268eaf4..f27d87e7 100644 --- a/documentation/guide-dataaccess-layer.asciidoc +++ b/documentation/guide-dataaccess-layer.asciidoc @@ -1,18 +1,18 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Data-Access Layer +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The data-access layer is responsible for all outgoing connections to access and process data. This is mainly about accessing data from a persistent data-store. External system could also be accessed from the data-access layer if they match this definition, e.g. a mongo-db via rest services. Note: In the link:guide-structure-modern.asciidoc[modern project structure], this layer is replaced by the link:guide-domain-layer.asciidoc[domain layer]. == Database +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + You need to make your choice for a database. Options are documented https://github.com/devonfw/devonfw-guide/blob/master/general/db/guide-database.asciidoc[here]. The classical approach is to use a Relational Database Management System (RDMS). In such a case, we strongly recommend to follow our link:guide-jpa.asciidoc[JPA Guide]. Some NoSQL databases are supported by https://spring.io/projects/spring-data[spring-data] so you can consider the link:guide-repository.asciidoc[repository guide]. diff --git a/documentation/guide-database-migration.asciidoc b/documentation/guide-database-migration.asciidoc index 7c022f2f..bc8d7852 100644 --- a/documentation/guide-database-migration.asciidoc +++ b/documentation/guide-database-migration.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Database Migration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + When you have a schema-based https://github.com/devonfw/devonfw-guide/blob/master/general/db/guide-database.asciidoc[database], you need a solution for schema versioning and migration for your database. A specific release of your app requires a corresponding version of the schema in the database to run. @@ -23,6 +21,8 @@ Also any version of your database schema can be present and you will always end == Options for database migration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For database migration you can choose between the following options: * link:guide-flyway.asciidoc[flyway] (KISS based approach with migrations as SQL) diff --git a/documentation/guide-datatype.asciidoc b/documentation/guide-datatype.asciidoc index 001aae57..68ca5e5b 100644 --- a/documentation/guide-datatype.asciidoc +++ b/documentation/guide-datatype.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Datatypes +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + [quote, mmm project, datatype javadoc] ____ A datatype is an object representing a value of a specific type with the following aspects: @@ -31,6 +29,8 @@ ____ See http://m-m-m.sourceforge.net/apidocs/net/sf/mmm/util/lang/api/Datatype.html[mmm datatype javadoc]. == Datatype Packaging + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For the devonfw we use a common link:coding-conventions.asciidoc#packages[packaging schema]. The specifics for datatypes are as following: @@ -43,15 +43,25 @@ The specifics for datatypes are as following: |============================================= == Technical Concerns + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Many technologies like Dozer and QueryDSL's (alias API) are heavily based on reflection. For them to work properly with custom datatypes, the frameworks must be able to instantiate custom datatypes with no-argument constructors. It is therefore recommended to implement a no-argument constructor for each datatype of at least +protected+ visibility. == Datatypes in Entities + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The usage of custom datatypes in entities is explained in the link:guide-jpa.asciidoc#entities-and-datatypes[persistence layer guide]. == Datatypes in Transfer-Objects +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === XML + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For mapping datatypes with JAXB see link:guide-xml.asciidoc[XML guide]. === JSON + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For mapping datatypes from and to JSON see link:guide-json#json-custom-mapping.asciidoc[JSON custom mapping]. \ No newline at end of file diff --git a/documentation/guide-dependency-injection.asciidoc b/documentation/guide-dependency-injection.asciidoc index 21cf93fd..1d3c63e4 100644 --- a/documentation/guide-dependency-injection.asciidoc +++ b/documentation/guide-dependency-injection.asciidoc @@ -1,11 +1,9 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Dependency Injection + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Dependency injection is one of the most important design patterns and is a key principle to a modular and component based architecture. The Java Standard for dependency injection is http://docs.oracle.com/javaee/6/api/javax/inject/package-summary.html[javax.inject (JSR330)] that we use in combination with http://docs.oracle.com/javaee/5/api/javax/annotation/package-summary.html[JSR250]. Additionally, for scoping you can use CDI (Context and Dependency Injection) from https://jcp.org/en/jsr/detail?id=365[JSR365]. @@ -14,6 +12,8 @@ There are many frameworks which support this standard including all recent Java Therefore in devonfw we rely on these open standards and can propagate patterns and code examples that work independent from the underlying frameworks. == Key Principles + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Within dependency injection a _bean_ is typically a reusable unit of your application providing an encapsulated functionality. This _bean_ can be injected into other beans and it should in general be replaceable. As an example we can think of a link:guide-usecase.asciidoc[use-case], a link:guide-repository.asciidoc[repository], etc. @@ -31,6 +31,8 @@ To follow the KISS (keep it small and simple) principle we avoid advanced featur For important components we should separate a self-contained API documented with JavaDoc from its implementation. Code from other components that wants to use the implementation shall only rely on the API. However, for things that will never be exchanged no API as interface is required you can skip such separation. == Example Bean + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Here you can see the implementation of an example bean using dependency injection: [source, java] ---- @@ -65,10 +67,14 @@ Now our bean can be injected into other beans using `@Inject` annotation either In case you omit the interface, you should also omit the `Impl` suffix or instead use `Bean` as suffix. == Multiple bean implementations + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In some cases you might have multiple implementations as beans for the same interface. The following sub-sections handle the different scenarios to give you guidance. === Only one implementation in container + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In some cases you still have only one implementation active as bean in the container at runtime. A typical example is that you have different implemenations for test and main usage. This case is easy, as `@Inject` will always be unique. @@ -76,6 +82,8 @@ The only thing you need to care about is how to configure your framework (spring In spring this can be archived via the proprietary `@Profile` annotaiton. === Injecting all of multiple implementations + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In some situations you may have an interface that defines a kind of "plugin". You can have multiple implementations in your container and want to have all of them injected. Then you can request a list with all the bean implementations via the interface as in the following example: @@ -90,6 +98,8 @@ Please note that the injection will fail (at least in spring), when there is no So you do not get an empty list injected but will get an exception on startup. === Injecting one of multiple implementations + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Another scenario is that you have multiple implementations in your container coexisting, but for injection you may want to choose a specific implementation. Here you could use the `@Named` annotation to specify a unique identifier for each implementation what is called qualified injection: [source, java] @@ -175,6 +185,8 @@ While the principle to separate API and implementation and strictly decouple fro you should always consider KISS, lean, and agile in contrast and balance pros and cons instead of blindly following dogmas. == Imports + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Here are the import statements for the most important annotations for dependency injection [source, java] ---- @@ -188,6 +200,8 @@ import javax.annotation.PreDestroy; ---- == Dependencies + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Please note that with https://jakarta.ee/[Jakarta EE] the dependencies have changed. When you want to start with Jakarta EE you should use these dependencies to get the annoations for dependency injection: diff --git a/documentation/guide-domain-layer.asciidoc b/documentation/guide-domain-layer.asciidoc index f797e065..898a12d1 100644 --- a/documentation/guide-domain-layer.asciidoc +++ b/documentation/guide-domain-layer.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Domain Layer +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The domain layer is responsible for the data-model and mapping it to a https://github.com/devonfw/devonfw-guide/blob/master/general/db/guide-database.asciidoc[database]. The most common approach is to use a Relational Database Management System (RDMS). In such a case, we strongly recommend to follow our link:guide-jpa.asciidoc[JPA Guide]. Some NoSQL databases are supported by https://spring.io/projects/spring-data[spring-data], so you can consider the link:guide-repository.asciidoc[repository guide]. diff --git a/documentation/guide-dto.asciidoc b/documentation/guide-dto.asciidoc index febd9520..a47a61d8 100644 --- a/documentation/guide-dto.asciidoc +++ b/documentation/guide-dto.asciidoc @@ -1,12 +1,8 @@ :toc: macro toc::[] - - -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = DTO approach +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + As described in link:guide-structure-modern.asciidoc[our modern structure guide], for application e.g. with microservices architecture where we build smaller applications compared to monoliths, we recommend keeping things as simple as possible. The same principle applies to transfer object. Instead of using different types of transfer objects for each entity such as link:guide-eto-cto.asciidoc[ETO and CTO], we highly suggest using one _data transfer object_ (DTO) named `«BusinessObject»Dto`. diff --git a/documentation/guide-eto-cto.asciidoc b/documentation/guide-eto-cto.asciidoc index e8e8afef..5c91e4f7 100644 --- a/documentation/guide-eto-cto.asciidoc +++ b/documentation/guide-eto-cto.asciidoc @@ -1,21 +1,23 @@ :toc: macro toc::[] - - -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = ETO and CTO approach +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == ETO + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For each link:guide-jpa.asciidoc#entity[persistent entity] `«BusinessObject»Entity` we create or generate a corresponding _entity transfer object_ (ETO) named `«BusinessObject»Eto`. It has the same properties except for relations. == BO + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In order to centralize the properties (getters and setters with their javadoc) we create a common interface `«BusinessObject»` implemented both by the entity and its ETO. This also gives us compile-time safety that link:guide-beanmapping.asciidoc[bean-mapper] can properly map all properties between entity and ETO. == CTO + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. If we need to pass an entity with its relation(s) we create a corresponding _composite transfer object_ (CTO) named `«BusinessObject»«Subset»Cto` that only contains other transfer-objects or collections of them. Here `«Subset»` is empty for the canonical CTO that holds the ETO together with all its relations. This is what can be generated automatically with https://github.com/devonfw/cobigen[CobiGen]. However, be careful to generate CTOs without thinking and considering design. diff --git a/documentation/guide-exceptions.asciidoc b/documentation/guide-exceptions.asciidoc index 2a535477..fa09d1e2 100644 --- a/documentation/guide-exceptions.asciidoc +++ b/documentation/guide-exceptions.asciidoc @@ -1,14 +1,14 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Exception Handling +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == Exception Principles + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For exceptions we follow these principles: * We only use exceptions for _exceptional_ situations and not for programming control flows, etc. Creating an exception in Java is expensive and hence should not be done for simply testing whether something is present, valid or permitted. In the latter case design your API to return this as a regular result. @@ -29,6 +29,8 @@ If you want to avoid additional dependencies, you can implement your own solutio == Exception Example + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Here is an exception class from our sample application: [source,java] @@ -86,6 +88,8 @@ public interface NlsBundleApplicationRoot extends NlsBundle { -------- == Handling Exceptions + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For catching and handling exceptions we follow these rules: * We do not catch exceptions just to wrap or to re-throw them. @@ -99,6 +103,8 @@ The exception facade has to ... > An unexpected technical error has occurred. We apologize any inconvenience. Please try again later. == Common Errors + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The following errors may occur in any devon application: .Common Exceptions diff --git a/documentation/guide-feature-toggle.asciidoc b/documentation/guide-feature-toggle.asciidoc index 1e800f65..2f52733d 100644 --- a/documentation/guide-feature-toggle.asciidoc +++ b/documentation/guide-feature-toggle.asciidoc @@ -1,22 +1,24 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Feature-Toggles +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The most software developing teams use Feature-Branching to be able to work in parallel and maintain a stable main branch in the VCS. However Feature-Branching might not be the ideal tool in every case because of big merges and isolation between development groups. In many cases, Feature-Toggles can avoid some of these problems, so these should definitely be considered to be used in the collaborative software development. == Implementation with the devonfw +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To use Feature-Toggles with the devonfw, use the Framework http://www.togglz.org/[Togglz] because it has all the features generally needed and provides a great documentation. For a pretty minimal working example, also see https://github.com/florianluediger/oasp4j[this fork]. === Preparation +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The following example takes place in the `oasp-sample-core` project, so the necessary dependencies have to be added to the according `pom.xml` file. Required are the main Togglz project including Spring support, the Togglz console to graphically change the feature state and the Spring security package to handle authentication for the Togglz console. [source,xml] @@ -52,6 +54,8 @@ togglz.console.secured=false === Small features +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For small features, a simple query of the toggle state is often enough to achieve the desired functionality. To illustrate this, a simple example follows, which implements a toggle to limit the page size returned by the staffmanagement. See https://github.com/florianluediger/oasp4j/commit/e55c3c7cfcb42efe4f279dc673cced730abd580a[here] for further details. This is the current implementation to _toggle_ the feature: @@ -99,6 +103,8 @@ This way, you can easily switch the feature on or off by using the administratio === Extensive features +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + When implementing extensive features, you might want to consider using the strategy design pattern to maintain the overview of your software. The following example is an implementation of a feature which adds a 25% discount to all products managed by the offermanagement. .Therefore there are two strategies needed: @@ -152,14 +158,20 @@ private PaginatedListTo addDiscountToOffers(PaginatedListTo\__ (e.g.: V12345__Add_new_table.sql). diff --git a/documentation/guide-i18n.asciidoc b/documentation/guide-i18n.asciidoc index 6785576b..18bda1d9 100644 --- a/documentation/guide-i18n.asciidoc +++ b/documentation/guide-i18n.asciidoc @@ -1,12 +1,8 @@ :toc: macro toc::[] - - -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Internationalization + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. //The property file doesn't exist anymore but the example looks fine. Keep it? Internationalization (I18N) is about writing code independent from locale-specific information. For I18N of text messages we are suggesting @@ -20,6 +16,8 @@ In devonfw we have developed a solution to manage text internationalization. dev == Binding locale information to the user +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We have defined two different points to bind locale information to user, depending on user is authenticated or not. * User not authenticated: devonfw intercepts unsecured request and extract locale from it. At first, we try to extract a `language` parameter from the request and if it is not possible, we extract locale from Àccept-language` header. @@ -32,6 +30,8 @@ image::images/i18n.png["Internationalization",scaledwidth="80%",align="center"] == Getting internationalizated messages +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + devonfw has a bean that manage i18n message resolution, the `ApplicationLocaleResolver.` This bean is responsible to get the current user and extract locale information from it and read the correct properties file to get the message. The i18n properties file must be called `ApplicationMessages_la_CO.properties` where la=language and CO=country. This is an example of a i18n properties file for English language to translate devonfw sample user roles: diff --git a/documentation/guide-jdk.asciidoc b/documentation/guide-jdk.asciidoc index bed0ccab..20388073 100644 --- a/documentation/guide-jdk.asciidoc +++ b/documentation/guide-jdk.asciidoc @@ -1,16 +1,16 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Java Development Kit +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The https://en.wikipedia.org/wiki/Java_Development_Kit[Java Development Kit] is an implementation of the Java platform. It provides the https://en.wikipedia.org/wiki/Java_virtual_machine[Java Virtual Machine] (JVM) and the Java Runtime Environment (JRE). == Editions +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The JDK exists in different editions: * https://openjdk.java.net/[OpenJDK] is a free and open-source edition of the JDK. @@ -31,6 +31,8 @@ The easiest way to get all this setup for developers is using https://github.com == Garbage Collection +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + A key feature of Java is automatic garbage collection (GC). Over time different garbage collectors have been implemented within the JVM. The good news is that usually you do not have to care about all this. @@ -51,6 +53,8 @@ For more details see https://sematext.com/blog/java-garbage-collection-logs/[her == Thread Dump +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Sometimes you may face concurrency issues or even deadlocks where threads block each other. In such case you should https://www.baeldung.com/java-thread-dump[create a thread-dump]. We even recommend you to create a series of e.g. 3-5 thread-dumps with a short delay of e.g. a minute bettwen each of them. @@ -58,6 +62,8 @@ This will help you to trace down problems of waiting or blocked threads. == Upgrading +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Until Java 8 compatibility was one of the key aspects for Java version updates (after the mess on the Swing updates with Java2 many years ago). However, Java 9 introduced a lot of breaking changes. This documentation wants to share the experience we collected in devonfw when upgrading from Java 8 to newer versions. @@ -65,9 +71,13 @@ First of all we separate runtime changes that you need if you want to build your from changes required to also build your software with more recent JDKs (e.g. JDK 11 or 12). === Runtime Changes + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. This section describes required changes to your software in order to make it run also with versions newer than Java 8. ==== Classes removed from JDK + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The first thing that most users hit when running their software with newer Java versions is a `ClassNotFoundException` like this: ``` Caused by: java.lang.ClassNotFoundException: javax.xml.bind.JAXBException @@ -91,6 +101,8 @@ The following table gives you the required hints to make your software work even |============================================= ==== 3rd Party Updates + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Further, internal and inofficial APIs (e.g. `sun.misc.Unsafe`) have been removed. These are typically not used by your software directly but by low-level 3rd party libraries like `asm` that need to be updated. Also simple things like the Java version have changed (from `1.8.x` to `9.x`, `10.x`, `11.x`, `12.x`, etc.). @@ -112,13 +124,19 @@ Therefore the following table gives an overview of common 3rd party libraries th |============================================= ==== ResourceBundles + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For internationalization (i18n) and localization (l10n) `ResourceBundle` is used for language and country specific texts and configurations as properties (e.g. `MyResourceBundle_de.properties`). With Java modules there are changes and impacts you need to know to get things working. The most important change is documented in the https://docs.oracle.com/javase/9/docs/api/java/util/ResourceBundle.html#bundleprovider[JavaDoc of ResourceBundle]. However, instead of using https://docs.oracle.com/javase/9/docs/api/java/util/spi/ResourceBundleProvider.html[ResourceBundleProvider] and refactoring your entire code causing incompatibilities, you can simply put the resource bundles in a regular JAR on the classpath rather than a named module (or into the lauching app). If you want to implement (new) Java modules with i18n support, you can have a look at https://github.com/m-m-m/nls#mmm-nls[mmm-nls]. === Buildtime Changes + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. If you also want to change your build to work with a recent JDK you also need to ensure that test frameworks and maven plugins properly support this. ==== Findbugs + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Findbugs does not work with Java 9+ and is actually a dead project. The new findbugs is https://spotbugs.github.io/[SpotBugs]. For maven the new solution is https://spotbugs.github.io/spotbugs-maven-plugin/[spotbugs-maven-plugin]: @@ -132,6 +150,8 @@ For maven the new solution is https://spotbugs.github.io/spotbugs-maven-plugin/[ ==== Test Frameworks +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + .Minimum recommended versions of common 3rd party test frameworks for Java 9+ @@ -143,6 +163,8 @@ For maven the new solution is https://spotbugs.github.io/spotbugs-maven-plugin/[ ==== Maven Plugins +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + .Minimum recommended versions of common maven plugins for Java 9+ [options="header"] |============================================= @@ -157,6 +179,8 @@ For maven the new solution is https://spotbugs.github.io/spotbugs-maven-plugin/[ ==== Maven Usage +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + With Java modules you can not run Javadoc standalone anymore or you will get this error when running `mvn javadoc:javadoc`: ``` [ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:3.1.1:javadoc (default-cli) on project mmm-base: An error has occurred in Javadoc report generation: @@ -171,6 +195,8 @@ mvn compile javadoc:javadoc ``` == Sources and Links + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We want to give credits and say thanks to the following articles that have been there before and helped us on our way: * https://blog.codefx.org/java/java-9-migration-guide/[Java 9 Migration Guide: The Seven Most Common Challenges] diff --git a/documentation/guide-jee.asciidoc b/documentation/guide-jee.asciidoc index 03b62c6e..817cba19 100644 --- a/documentation/guide-jee.asciidoc +++ b/documentation/guide-jee.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = JEE +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This section is about Java Enterprise Edition (JEE). Regarding to our link:architecture#key-principles.asciidoc[key principles] we focus on open standards. For Java this means that we consider official standards from Java Standard and Enterprise Edition as first choice for considerations. @@ -19,6 +17,8 @@ Please note that JEE has nowadays been replaced by https://jakarta.ee/[JakartaEE link:quarkus.asciidoc[Quarkus] already supports this and also link:spring.asciidoc[spring]-boot supports it starting from version `2.6` so for new projects you should consider to directly use only JakartaEE. == Application-Server + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We designed everything based on standards to work with different technology stacks and servlet containers. However, we strongly encourage to use modern and leightweight frameworks such as link:spring.asciidoc[spring] or link:quarkus.asciidoc[quarkus]. You are free to decide for a JEE application server but here is a list of good reasons for our decision: diff --git a/documentation/guide-jms.asciidoc b/documentation/guide-jms.asciidoc index dbb15f84..2b3e6645 100644 --- a/documentation/guide-jms.asciidoc +++ b/documentation/guide-jms.asciidoc @@ -1,15 +1,15 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Messaging +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Messaging in Java is done using the https://en.wikipedia.org/wiki/Java_Message_Service[JMS] standard from JEE. == Products + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For messaging you need to choose a JMS provider such as: * https://www.rabbitmq.com/[RabbitMQ] @@ -17,9 +17,13 @@ For messaging you need to choose a JMS provider such as: * link:guide-oracle.asciidoc#messaging[Oracle Advanced Queuing] (esp. if you already use link:guide-oracle.asciidoc[Oracle RDBMS]) == Receiver + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. As a receiver of messages is receiving data from other systems it is located in the link:guide-service-layer.asciidoc[service-layer]. === JMS Listener + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A `JmsListener` is a class listening and consuming JMS messages. It should carry the suffix `JmsListener` and implement the `MessageListener` interface or have its listener method annotated with `@JmsListener`. This is illustrated by the following example: [source,java] @@ -48,6 +52,8 @@ public class BookingJmsListener /* implements MessageListener */ { == Sender +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The sending of JMS messages is considered as any other sending of data like link:guide-kafka.asciidoc[kafka] messages or RPC calls via link:guide-rest.asciidoc[REST] using link:guide-service-client.asciidoc[service-client], gRPC, etc. This will typically happen directly from a link:guide-usecase.asciidoc[use-case] in the link:guide-logic-layer.asciidoc[logic-layer]. However, the technical complexity of the communication and protocols itself shall be hidden from the use-case and not be part of the logic layer. diff --git a/documentation/guide-jmx.asciidoc b/documentation/guide-jmx.asciidoc index 702432cf..fb4689dd 100644 --- a/documentation/guide-jmx.asciidoc +++ b/documentation/guide-jmx.asciidoc @@ -1,12 +1,10 @@ :toc: toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = JMX +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + https://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html[JMX] (Java Management Extensions) is the official Java link:guide-monitoring.asciidoc[monitoring] solution. It is part of the JDK. Your application may provide monitoring information or receive monitoring related commands via `MBeans`. diff --git a/documentation/guide-jpa-idref.asciidoc b/documentation/guide-jpa-idref.asciidoc index b72d7664..92374254 100644 --- a/documentation/guide-jpa-idref.asciidoc +++ b/documentation/guide-jpa-idref.asciidoc @@ -1,17 +1,17 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = IdRef +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + IdRef can be used to reference other entities in TOs in order to make them type-safe and semantically more expressive. It is an optional concept in devon4j for more complex applications that make intensive use of relations and foreign keys. == Motivation +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Assuming you have a method signature like the following: [source,java] ---- @@ -33,6 +33,8 @@ Finally, when passing `IdRef` objects to such methods, we get compile errors in == IdRef and Mapping +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In order to easily map relations from entities to link:guide-transferobject.asciidoc[transfer-objects] and back, we can easily also put according getters and setters into our entities: [source,java] @@ -88,6 +90,8 @@ This way the bean-mapper can automatically map from your entity (`ContractEntity == JpaHelper and EntityManager access +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In the above example we used `JpaHelper.asEntity` to convert the foreign key (`IdRef`) to the according entity (`CustomerEntity`). This will internally use `EntityManager.getReference` to properly create a JPA entity. The alternative "solution" that may be used with `Long` instead of `IdRef` is typically: @@ -124,6 +128,8 @@ when link:tutorial-newapp.asciidoc[creating a devon4j app]. === JpaHelper and spring-test +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Further, you also want your code to work in integration tests. Spring-test provides a lot of magic under the hood to make integration testing easy for you. To boost the performance when running multiple tests, spring is smart and avoids creating the same spring-context multiple times. diff --git a/documentation/guide-jpa-performance.asciidoc b/documentation/guide-jpa-performance.asciidoc index 21bba5a7..5f05f37a 100644 --- a/documentation/guide-jpa-performance.asciidoc +++ b/documentation/guide-jpa-performance.asciidoc @@ -1,11 +1,9 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = JPA Performance + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. When using JPA the developer sometimes does not see or understand where and when statements to the database are triggered. [quote, Dan Allen, https://epdf.tips/seam-in-action.html] ____ @@ -14,6 +12,8 @@ ____ So in case you do not understand what is going on under the hood of JPA, you will easily run into performance issues due to lazy loading and other effects. == N plus 1 Problem + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The most prominent phenomena is call the `N+1 Problem`. We use entities from our https://github.com/devonfw/my-thai-star[MTS] demo app as an example to explain the problem. There is a https://github.com/devonfw/my-thai-star/blob/develop/java/mtsj/core/src/main/java/com/devonfw/application/mtsj/dishmanagement/dataaccess/api/DishEntity.java[DishEntity] that has a `@ManyToMany` relation to @@ -32,6 +32,8 @@ Now `dish.getExtras()` is loaded lazy. Therefore the JPA vendor will provide a l Now `findDishById` caused 1 initial query statement and for any number `N` of ingredients we are causing an additional query statement. This makes a total of `N+1` statements. As causing statements to the database is an expensive operation with a lot of overhead (creating connection, etc.) this ends in bad performance and is therefore a problem (the N+1 Problem). == Solving N plus 1 Problem + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. To solve the N+1 Problem you need to change your code to only trigger a single statement instead. This can be archived in various ways. The most universal solution is to use `FETCH JOIN` in order to pre-load the nested `N` child entities into the first level cache of the JPA vendor implementation. This will behave very similar as if the `@ManyToMany` relation to `IngredientEntity` was having `FetchType.EAGER` but only for the specific query and not in general. Because changing `@ManyToMany` to `FetchType.EAGER` would cause bad performance for other usecases where only the dish but not its extra ingredients are needed. For this reason all relations, including `@OneToOne` should always be `FetchType.LAZY`. Back to our example we simply replace `dao.findDishById(dishId)` with `dao.findDishWithExtrasById(dishId)` that we implement by the following JPQL query: [source,sql] ---- diff --git a/documentation/guide-jpa-query.asciidoc b/documentation/guide-jpa-query.asciidoc index 8832d30f..729d2eb8 100644 --- a/documentation/guide-jpa-query.asciidoc +++ b/documentation/guide-jpa-query.asciidoc @@ -1,16 +1,16 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Queries + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The http://www.oracle.com/technetwork/java/javaee/tech/persistence-jsp-140049.html[Java Persistence API (JPA)] defines its own query language, the https://docs.oracle.com/html/E13946_01/ejb3_langref.html[_java persistence query language_ (JPQL)] (see also https://docs.oracle.com/javaee/7/tutorial/persistence-querylanguage.htm[JPQL tutorial]), which is similar to SQL but operates on entities and their attributes instead of tables and columns. The simplest CRUD-Queries (e.g. find an entity by its ID) are already build in the devonfw CRUD functionality (via link:guide-repository.asciidoc[Repository] or link:guide-dao.asciidoc[DAO]). For other cases you need to write your own query. We distinguish between _static_ and _dynamic_ queries. xref:static-queries[Static queries] have a fixed JPQL query string that may only use parameters to customize the query at runtime. Instead, xref:dynamic-queries[dynamic queries] can change their clauses (`WHERE`, `ORDER BY`, `JOIN`, etc.) at runtime depending on the given search criteria. == Static Queries + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. E.g. to find all https://github.com/devonfw/my-thai-star/blob/develop/java/mtsj/core/src/main/java/com/devonfw/application/mtsj/dishmanagement/dataaccess/api/DishEntity.java[DishEntries] (from MTS sample app) that have a price not exceeding a given `maxPrice` we write the following JPQL query: [source,sql] ---- @@ -19,6 +19,8 @@ SELECT dish FROM DishEntity dish WHERE dish.price <= :maxPrice Here `dish` is used as alias (variable name) for our selected `DishEntity` (what refers to the simple name of the Java entity class). With `dish.price` we are referring to the Java property `price` (`getPrice()`/`setPrice(...)`) in `DishEntity`. A named variable provided from outside (the search criteria at runtime) is specified with a colon (`:`) as prefix. Here with `:maxPrice` we reference to a variable that needs to be set via `query.setParameter("maxPrice", maxPriceValue)`. JPQL also supports indexed parameters (`?`) but they are discouraged because they easily cause confusion and mistakes. === Using Queries to Avoid Bidirectional Relationships + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. With the usage of queries it is possible to avoid exposing relationships or modelling bidirectional relationships, which have some disadvantages (see link:guide-jpa.asciidoc#relationships[relationships]). This is especially desired for relationships between entities of different business components. So for example to get all https://github.com/devonfw/my-thai-star/blob/develop/java/mtsj/core/src/main/java/com/devonfw/application/mtsj/ordermanagement/dataaccess/api/OrderLineEntity.java[OrderLineEntities] for a specific https://github.com/devonfw/my-thai-star/blob/develop/java/mtsj/core/src/main/java/com/devonfw/application/mtsj/ordermanagement/dataaccess/api/OrderEntity.java[OrderEntity] without using the `orderLines` relation from `OrderEntity` the following query could be used: [source,sql] @@ -27,6 +29,8 @@ SELECT line FROM OrderLineEntity line WHERE line.order.id = :orderId ---- == Dynamic Queries + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For dynamic queries, we use the http://querydsl.com/static/querydsl/latest/reference/html/ch02.html[JPA] module for http://www.querydsl.com/[Querydsl]. Querydsl also supports other modules such as http://querydsl.com/static/querydsl/latest/reference/html/ch02s07.html[MongoDB], and http://querydsl.com/static/querydsl/latest/reference/html/ch02s05.html[Apache Lucene]. It allows to implement queries in a powerful but readable and type-safe way (unlike Criteria API). If you already know JPQL, you will quickly be able to read and write Querydsl code. It feels like JPQL but implemented in Java instead of plain text. To use Querydsl in your Maven project, add the following dependencies: @@ -119,6 +123,8 @@ The `orderBy` method is used to sort the query results according to certain crit For spring, devon4j provides another approach that you can use for your Spring applications to implement Querydsl logic without having to use these metaclasses. An example can be found link:spring/guide-querydsl-spring.asciidoc[here]. == Native Queries + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Spring Data supports the use of _native queries_. Native queries use simple native SQL syntax that is not parsed in JPQL. This allows you to use all the features that your database supports. The downside to this is that database portability is lost due to the absence of an abstraction layer. Therefore, the queries may not work with another database because it may use a different syntax. @@ -143,9 +149,13 @@ List products = query.getResultList(); NOTE: Be sure to use the name of the table when using native queries, while you must use the entity name when implementing queries with JPQL. == Using Wildcards + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For flexible queries it is often required to allow wildcards (especially in xref:dynamic_queries[dynamic queries]). While users intuitively expect glob syntax, the SQL and JPQL standards work differently. Therefore, a mapping is required. devonfw provides this on a lower level with https://github.com/devonfw/devon4j/blob/develop/modules/basic/src/main/java/com/devonfw/module/basic/common/api/query/LikePatternSyntax.java[LikePatternSyntax] and on a higher level with https://github.com/devonfw/devon4j/blob/develop/modules/jpa-basic/src/main/java/com/devonfw/module/jpa/dataaccess/api/QueryUtil.java#L54[QueryUtil] (see https://github.com/devonfw/devon4j/blob/develop/modules/jpa-basic/src/main/java/com/devonfw/module/jpa/dataaccess/api/QueryHelper.java#L199[QueryHelper.newStringClause(...)]). == Pagination + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. When dealing with large amounts of data, an efficient method of retrieving the data is required. Fetching the entire data set each time would be too time consuming. Instead, __Paging__ is used to process only small subsets of the entire data set. If you are using link:guide-repository.asciidoc[Spring Data repositories] you will get pagination support out of the box by providing the interfaces https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/domain/Pageable.html[Page] and https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/domain/Pageable.html[Pageable]: @@ -168,6 +178,8 @@ Page dishes = dishRepository.findAll(pageable); === Paging with Querydsl +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Pagination is also supported for dynamic queries with Querydsl: [source,java] @@ -191,6 +203,8 @@ Pagination is also supported for dynamic queries with Querydsl: ---- === Pagination example + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For the table entity we can make a search request by accessing the REST endpoint with pagination support like in the following examples: @@ -277,12 +291,18 @@ POST mythaistar/services/rest/tablemanagement/v1/table/search ---- === Pagingation in devon4j-spring + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For spring applications, devon4j also offers its own solution for pagination. You can find an example of this link:spring/guide-querydsl-spring.asciidoc#pagination[here]. == Query Meta-Parameters + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Queries can have meta-parameters and that are provided via `SearchCriteriaTo`. Besides paging (see above) we also get https://github.com/devonfw/devon4j/blob/develop/modules/jpa-basic/src/main/java/com/devonfw/module/jpa/dataaccess/api/QueryHelper.java#L51[timeout support]. == Advanced Queries + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Writing queries can sometimes get rather complex. The current examples given above only showed very simple basics. Within this topic a lot of advanced features need to be considered like: * https://www.w3schools.com/sql/sql_join.asp[Joins] diff --git a/documentation/guide-jpa.asciidoc b/documentation/guide-jpa.asciidoc index d4ecfce7..28abc90b 100644 --- a/documentation/guide-jpa.asciidoc +++ b/documentation/guide-jpa.asciidoc @@ -1,19 +1,21 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Java Persistence API +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For mapping java objects to a relational database we use the http://www.oracle.com/technetwork/java/javaee/tech/persistence-jsp-140049.html[Java Persistence API (JPA)]. As JPA implementation we recommend to use http://hibernate.org/orm/[Hibernate]. For general documentation about JPA and Hibernate follow the links above as we will not replicate the documentation. Here you will only find guidelines and examples how we recommend to use it properly. The following examples show how to map the data of a database to an entity. As we use JPA we abstract from link:guide-sql.asciidoc[SQL] here. However, you will still need a https://en.wikipedia.org/wiki/Data_definition_language[DDL] script for your schema and during maintenance also link:guide-database-migration.asciidoc[database migrations]. Please follow our link:guide-sql.asciidoc[SQL guide] for such artifacts. == Entity + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Entities are part of the persistence layer and contain the actual data. They are POJOs (Plain Old Java Objects) on which the relational data of a database is mapped and vice versa. The mapping is configured via JPA annotations (`javax.persistence`). Usually an entity class corresponds to a table of a database and a property to a column of that table. A persistent entity instance then represents a row of the database table. === A Simple Entity + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The following listing shows a simple example: [source,java] @@ -44,6 +46,8 @@ Note that every entity class needs a constructor with public or protected visibi Entities should be simple POJOs and not contain business logic. === Entities and Datatypes + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Standard datatypes like `Integer`, `BigDecimal`, `String`, etc. are mapped automatically by JPA. Custom link:guide-datatype.asciidoc[datatypes] are mapped as serialized xref:blob[BLOB] by default what is typically undesired. In order to map atomic custom datatypes (implementations of`+SimpleDatatype`) we implement an `AttributeConverter`. Here is a simple example: [source,java] @@ -65,9 +69,13 @@ The annotation `@Converter` is detected by the JPA vendor if the annotated class In case you have a composite datatype that you need to map to multiple columns the JPA does not offer a real solution. As a workaround you can use a bean instead of a real datatype and declare it as xref:embeddable[`@Embeddable`]. If you are using Hibernate you can implement `CompositeUserType`. Via the `@TypeDef` annotation it can be registered to Hibernate. If you want to annotate the `CompositeUserType` implementation itself you also need another annotation (e.g. `MappedSuperclass` tough not technically correct) so it is found by the scan. ==== Enumerations + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. By default JPA maps Enums via their ordinal. Therefore the database will only contain the ordinals (0, 1, 2, etc.) . So , inside the database you can not easily understand their meaning. Using `@Enumerated` with `EnumType.STRING` allows to map the enum values to their name (`Enum.name()`). Both approaches are fragile when it comes to code changes and refactoring (if you change the order of the enum values or rename them) after the application is deployed to production. If you want to avoid this and get a robust mapping you can define a dedicated string in each enum value for database representation that you keep untouched. Then you treat the enum just like any other xref:entities-and-datatypes[custom datatype]. ==== BLOB + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. If binary or character large objects (BLOB/CLOB) should be used to store the value of an attribute, e.g. to store an icon, the `@Lob` annotation should be used as shown in the following listing: [source,java] ---- @@ -86,6 +94,8 @@ public Blob getAttachment() { ---- ==== Date and Time + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. To store date and time related values, the temporal annotation can be used as shown in the listing below: [source,java] ---- @@ -99,6 +109,8 @@ Until Java8 the java data type `java.util.Date` (or Jodatime) has to be used. Mixing these two granularities can cause problems when comparing one value to another. This is why we *only* use `TemporalType.TIMESTAMP`. ==== QueryDSL and Custom Types + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Using the Aliases API of QueryDSL might result in an `InvalidDataAccessApiUsageException` when using custom datatypes in entity properties. This can be circumvented in two steps: . Ensure you have the following maven dependencies in your project (`core` module) to support custom types via the Aliases API: @@ -118,6 +130,8 @@ Using the Aliases API of QueryDSL might result in an `InvalidDataAccessApiUsageE . Make sure, that all your custom types used in entities provide a non-argument constructor with at least visibility level `protected`. === Primary Keys + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We only use simple Long values as primary keys (IDs). By default it is auto generated (`@GeneratedValue(strategy=GenerationType.AUTO)`). This is already provided by the class `com.devonfw..general.dataaccess.api.AbstractPersistenceEntity` within the link:guide-structure-classic.asciidoc#architecture-mapping[classic project structure] respectively `com.devonfw..general.domain.model.AbstractPersistenceEntity` within the link:guide-structure-modern.asciidoc#architecture-mapping[modern project structure], that you can extend. @@ -136,7 +150,11 @@ In case you have business oriented keys (often as `String`), you can define an a Be sure to include "AUTO_INCREMENT" in your sql table field ID to be able to persist data (or similar for other databases). == Relationships + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. === n:1 and 1:1 Relationships + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Entities often do not exist independently but are in some relation to each other. For example, for every period of time one of the StaffMember's of the restaurant example has worked, which is represented by the class `WorkingTime`, there is a relationship to this StaffMember. The following listing shows how this can be modeled using JPA: @@ -165,6 +183,8 @@ To represent the relationship, an attribute of the type of the corresponding ent This is why the `@ManyToOne` annotation is used here. For 1:1 relationships the `@OneToOne` annotation can be used which works basically the same way. To be able to save information about the relation in the database, an additional column in the corresponding table of WorkingTime is needed which contains the primary key of the referenced StaffMember. With the `name` element of the `@JoinColumn` annotation it is possible to specify the name of this column. === 1:n and n:m Relationships + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The relationship of the example listed above is currently an unidirectional one, as there is a getter method for retrieving the `StaffMember` from the `WorkingTime` object, but not vice versa. To make it a bidirectional one, the following code has to be added to `StaffMember`: @@ -227,6 +247,8 @@ For 1:n relationships this solution has the disadvantage that more joins (in the Note that bidirectional n:m relationships are not allowed for applications based on devon4j. Instead a third entity has to be introduced, which "represents" the relationship (it has two n:1 relationships). === Eager vs. Lazy Loading + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Using JPA it is possible to use either lazy or eager loading. Eager loading means that for entities retrieved from the database, other entities that are referenced by these entities are also retrieved, whereas lazy loading means that this is only done when they are actually needed, i.e. when the corresponding getter method is invoked. Application based on devon4j are strongly advised to *always use lazy loading*. The JPA defaults are: @@ -241,6 +263,8 @@ So at least for `@ManyToOne` and `@OneToOne` you always need to override the def IMPORTANT: Please read the link:guide-jpa-performance.asciidoc[performance guide]. === Cascading Relationships + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For relations it is also possible to define whether operations are cascaded (like a recursion) to the related entity. By default, nothing is done in these situations. This can be changed by using the `cascade` property of the annotation that specifies the relation type (`@OneToOne`, `@ManyToOne`, `@OneToMany`, `@ManyToOne`). This property accepts a `CascadeType` that offers the following options: @@ -255,10 +279,14 @@ See http://meri-stuff.blogspot.de/2012/03/jpa-tutorial.html[here] for more infor === Typesafe Foreign Keys using IdRef +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For simple usage you can use `Long` for all your foreign keys. However, as an optional pattern for advanced and type-safe usage, we offer link:guide-jpa-idref.asciidoc[IdRef]. == Embeddable + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. An embeddable Object is a way to group properties of an xref:entity[entity] into a separate Java (child) object. Unlike with implement xref:relationships[relationships] the embeddable is not a separate entity and its properties are stored (embedded) in the same table together with the entity. This is helpful to structure and reuse groups of properties. The following example shows an `Address` implemented as an embeddable class: @@ -309,6 +337,8 @@ Using this `AddressEmbeddable` inside an entity class can be done like this: The `@Embedded` annotation needs to be used for embedded attributes. Note that if in all columns of the embeddable (here `Address`) are `null`, then the embeddable object itself is also `null` inside the entity. This has to be considered to avoid NullPointerException's. Further this causes some issues with primitive types in embeddable classes that can be avoided by only using object types instead. == Inheritance + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Just like normal java classes, xref:entity[entity] classes can inherit from others. The only difference is that you need to specify how to map a class hierarchy to database tables. Generic abstract super-classes for entities can simply be annotated with `@MappedSuperclass`. For all other cases the JPA offers the annotation `@Inheritance` with the property `strategy` talking an `InheritanceType` that has the following options: @@ -342,9 +372,13 @@ public class MyOtherEntity extends MyParentEntity implements MyChild { As a best practice we advise you to avoid entity hierarchies at all where possible and otherwise to keep the hierarchy as small as possible. In order to just ensure reuse or establish a common API you can consider a shared interface, a `@MappedSuperclass` or an `@Embeddable` instead of an entity hierarchy. == Repositories and DAOs + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For each entity a code unit is created that groups all database operations for that entity. We recommend to use link:guide-repository.asciidoc[spring-data repositories] for that as it is most efficient for developers. As an alternative there is still the classic approach using link:guide-dao.asciidoc[DAOs]. === Concurrency Control + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The concurrency control defines the way concurrent access to the same data of a database is handled. When several users (or threads of application servers) concurrently access a database, anomalies may happen, e.g. a transaction is able to see changes from another transaction although that one did, not yet commit these changes. Most of these anomalies are automatically prevented by the database system, depending on the http://en.wikipedia.org/wiki/Isolation_(database_systems)[_isolation level_] (property `hibernate.connection.isolation` in the `jpa.xml`, see http://docs.jboss.org/hibernate/orm/5.0/manual/en-US/html/ch03.html[here], or `quarkus.datasource.jdbc.transaction-isolation-level` in the `application.properties`). Another anomaly is when two stakeholders concurrently access a record, do some changes and write them back to the database. The JPA addresses this with different locking strategies (see http://www.objectdb.com/java/jpa/persistence/lock[here]). @@ -352,6 +386,8 @@ Another anomaly is when two stakeholders concurrently access a record, do some c As a best practice we are using optimistic locking for regular end-user link:guide-service-layer.asciidoc[services] (OLTP) and pessimistic locking for link:guide-batch-layer.asciidoc[batches]. === Optimistic Locking + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The class `com.devonfw.module.jpa.persistence.api.AbstractPersistenceEntity` already provides optimistic locking via a `modificationCounter` with the `@Version` annotation. Therefore JPA takes care of optimistic locking for you. When entities are transferred to clients, modified and sent back for update you need to ensure the `modificationCounter` is part of the game. If you follow our guides about link:guide-transferobject.asciidoc[transfer-objects] and link:guide-service-layer.asciidoc[services] this will also work out of the box. You only have to care about two things: @@ -361,6 +397,8 @@ Assume an entity `A` contains a collection of `B` entities. Should there be a lo According to KISS our recommendation is that the user gets an error displayed that tells him to do his change again on the recent data. Try to design your system and the work processing in a way to keep such conflicts rare and you are fine. === Pessimistic Locking + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For back-end link:guide-service-layer.asciidoc[services] and especially for link:guide-batch-layer.asciidoc[batches] optimistic locking is not suitable. A human user shall not cause a large batch process to fail because he was editing the same entity. Therefore such use-cases use pessimistic locking what gives them a kind of priority over the human users. In your xref:data-access-object[DAO] implementation you can provide methods that do pessimistic locking via http://docs.oracle.com/javaee/7/api/javax/persistence/EntityManager.html[`EntityManager`] operations that take a http://docs.oracle.com/javaee/7/api/javax/persistence/LockModeType.html[`LockModeType`]. Here is a simple example: [source,java] @@ -373,12 +411,18 @@ Use one of the types if you want to modify the entity later on, for read only ac As you might have noticed, the behavior of Hibernate deviates from what one would expect by looking at the `LockModeType` (especially `LockModeType.READ` should not cause a `SELECT ... FOR UPDATE` to be issued). The framework actually deviates from what is http://docs.oracle.com/javaee/7/api/javax/persistence/LockModeType.html[specified] in the JPA for unknown reasons. == Database Auditing + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. See link:guide-auditing.asciidoc[auditing guide]. == Testing Data-Access + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For testing of Entities and Repositories or DAOs see link:guide-testing.asciidoc#level-2-component-test[testing guide]. == Principles + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We strongly recommend these principles: * Use the JPA where ever possible and use vendor (hibernate) specific features only for situations when JPA does not provide a solution. In the latter case consider first if you really need the feature. @@ -387,6 +431,8 @@ We strongly recommend these principles: == Database Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For details on the configuration of the database connection and database logging of the individual framework, please refer to the respective configuration guide. For link:spring.asciidoc[spring] see link:spring/guide-spring-configuration.asciidoc#database-configuration[here]. @@ -394,13 +440,21 @@ For link:spring.asciidoc[spring] see link:spring/guide-spring-configuration.asci For link:quarkus.asciidoc[quarkus] see link:quarkus/guide-quarkus-configuration.asciidoc#database-configuration[here]. === Database Migration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. See link:guide-database-migration.asciidoc[database migration]. === Pooling + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. You typically want to pool JDBC connections to boost performance by recycling previous connections. There are many libraries available to do connection pooling. We recommend to use https://github.com/brettwooldridge/HikariCP[HikariCP]. For Oracle RDBMS see link:guide-oracle.asciidoc#pooling[here]. == Security + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. === SQL-Injection + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A common link:guide-security.asciidoc[security] threat is http://en.wikipedia.org/wiki/SQL_injection[SQL-injection]. Never build queries with string concatenation or your code might be vulnerable as in the following example: [source, java] ---- @@ -416,4 +470,6 @@ In order to prevent such injections you have to strictly follow our rules for xr * Please also consult the https://www.owasp.org/index.php/SQL_Injection_Prevention_Cheat_Sheet[SQL Injection Prevention Cheat Sheet]. === Limited Permissions for Application + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We suggest that you operate your application with a database user that has limited permissions so he can not modify the SQL schema (e.g. drop tables). For initializing the schema (DDL) or to do schema migrations use a separate user that is not used by the application itself. diff --git a/documentation/guide-json.asciidoc b/documentation/guide-json.asciidoc index e844aac8..3d30098c 100644 --- a/documentation/guide-json.asciidoc +++ b/documentation/guide-json.asciidoc @@ -1,16 +1,16 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = JSON +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + http://en.wikipedia.org/wiki/JSON[JSON] (JavaScript Object Notation) is a popular format to represent and exchange data especially for modern web-clients. For mapping Java objects to JSON and vice-versa there is no official standard API. We use the established and powerful open-source solution http://wiki.fasterxml.com/JacksonHome[Jackson]. Due to problems with the wiki of fasterxml you should try this alternative link: https://github.com/FasterXML/jackson#jackson-project-home-github[Jackson/AltLink]. == Configure JSON Mapping + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In order to avoid polluting business objects with proprietary Jackson annotations (e.g. `@JsonTypeInfo`, `@JsonSubTypes`, `@JsonProperty`) we propose to create a separate configuration class. Every devonfw application (sample or any app created from our link:tutorial-newapp.asciidoc[app-template]) therefore has a class called `ApplicationObjectMapperFactory` that extends +ObjectMapperFactory+ from the +devon4j-rest+ module. It looks like this: [source,java] @@ -26,6 +26,8 @@ public class ApplicationObjectMapperFactory extends ObjectMapperFactory { -------- == JSON and Inheritance + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. If you are using inheritance for your objects mapped to JSON then polymorphism can not be supported out-of-the box. So in general avoid polymorphic objects in JSON mapping. However, this is not always possible. Have a look at the following example from our sample application: [[img-rest-inheritance]] @@ -51,6 +53,8 @@ addSubtypes(new NamedType(MealEto.class, "Meal"), new NamedType(DrinkEto.class, We use `setBaseClasses` to register all top-level classes of polymorphic objects. Further we declare all concrete polymorphic sub-classes together with their symbolic name for the JSON format via `addSubtypes`. == Custom Mapping + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In order to map custom link:guide-datatype.asciidoc[datatypes] or other types that do not follow the Java bean conventions, you need to define a custom mapping. If you create objects dedicated for the JSON mapping you can easily avoid such situations. When this is not suitable follow these instructions to define the mapping: . As an example, the use of JSR354 (`javax.money`) is appreciated in order to process monetary amounts properly. However, without custom mapping, the default mapping of Jackson will produce the following JSON for a `MonetaryAmount`: diff --git a/documentation/guide-jwt.asciidoc b/documentation/guide-jwt.asciidoc index 47f25b7d..1159f21f 100644 --- a/documentation/guide-jwt.asciidoc +++ b/documentation/guide-jwt.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = JWT +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + https://jwt.io[JWT] (JSON Web Token) is an open standard (see https://tools.ietf.org/html/rfc7519[RFC 7519]) for creating link:guide-json.asciidoc[JSON] based access tokens that assert some number of claims. With an IT landscape divided into multiple smaller apps you want to avoid coupling all those apps or services tightly with your IAM (Identity & Access Management). Instead your apps simply expects a JWT as https://oauth.net/2/bearer-tokens/[bearer-token] in the `Authorization` HTTP header field. diff --git a/documentation/guide-kafka.asciidoc b/documentation/guide-kafka.asciidoc index f82c127c..ab4b675c 100644 --- a/documentation/guide-kafka.asciidoc +++ b/documentation/guide-kafka.asciidoc @@ -3,12 +3,10 @@ toc::[] WARNING: devon4j-kafka has been abandoned. Its main feature was the implementation of a retry pattern using multiple topics. This implementation has become an integral part of Spring Kafka. We recommend to use Spring Kafkas own implemenation for retries. -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Messaging Services +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Messaging Services provide an asynchronous communication mechanism between applications. Technically this is implemented using http://kafka.apache.org/documentation.html[Apache Kafka] . For link:spring.asciidoc[spring], devonfw uses link:https://spring.io/projects/spring-kafka[Spring-Kafka] as kafka framework. diff --git a/documentation/guide-liquibase.asciidoc b/documentation/guide-liquibase.asciidoc index 11e9289c..64b72c31 100644 --- a/documentation/guide-liquibase.asciidoc +++ b/documentation/guide-liquibase.asciidoc @@ -1,20 +1,22 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Liquibase +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + https://www.liquibase.org/[Liquibase] is a tool for link:guide-database-migration.asciidoc[database migration and schema versioning]. See https://github.com/devonfw/devon4j/issues/303[devon4j#303] for details and status. == Spring-boot usage +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For using liquibase in link:spring.asciidoc[spring] see https://docs.liquibase.com/tools-integrations/springboot/springboot.html[Using Liquibase with Spring Boot]. == Quarkus usage +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For uisng liquibase in link:quarkus.asciidoc[quarkus] see https://quarkus.io/guides/liquibase[Using Liquibase]. diff --git a/documentation/guide-log-monitoring.asciidoc b/documentation/guide-log-monitoring.asciidoc index 79b192cd..bb019ff6 100644 --- a/documentation/guide-log-monitoring.asciidoc +++ b/documentation/guide-log-monitoring.asciidoc @@ -1,12 +1,10 @@ :toc: toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Log-Monitoring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Log-monitoring is an aspect of link:guide-monitoring.asciidoc[monitoring] with a strict focus on link:guide-logging.asciidoc[logging]. With trends towards IT landscapes with many but much smaller apps the classicial approach to write log-files to the disc and let operators read those via SSH became entirely obsolete. Nowadays we have up to hundreds or even thousands of apps that themselves are clustered into multiple nodes. @@ -20,6 +18,8 @@ This approach gives the following benefits: == Options for log-monitoring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Typical products for such a log monitoring system are: * https://www.elastic.co/de/what-is/elk-stack[ELK-Stack] @@ -32,6 +32,8 @@ For Quarkus applications, you can get an insight into the topic by reading the g == API for log-monitoring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The "API" for logging to a log-monitoring system for your app is pretty simple: * Write your logs to standard out. diff --git a/documentation/guide-logging.asciidoc b/documentation/guide-logging.asciidoc index f8ee24a1..b848dded 100644 --- a/documentation/guide-logging.asciidoc +++ b/documentation/guide-logging.asciidoc @@ -1,17 +1,17 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Logging +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We recommend to use http://www.slf4j.org/[SLF4J] as API for logging, that has become a de facto standard in Java as it has a much better design than `java.util.logging` offered by the JDK. There are serveral implementations for SLF4J. For Spring applications our recommended implementation is http://logback.qos.ch/[Logback]. Quarkus uses JBoss Logging which provides a JBoss Log Manager implementation for SLF4J. For more information on logging in Quarkus, see the https://quarkus.io/guides/logging[Quarkus logging guide]. == Logging Dependencies +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To use Logback in your Spring application, you need to include the following dependencies: [source, xml] @@ -38,6 +38,8 @@ In devon4j these dependencies are provided by the https://github.com/devonfw/dev In Quarkus, SLF4J and the https://github.com/jboss-logging/slf4j-jboss-logmanager[`slf4j-jboss-logmanager`] are directly included in the Quarkus core runtime and can be used out of the box. == Logger Access + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The general pattern for accessing loggers from your code is a static logger instance per class using the following pattern: [source,java] @@ -56,9 +58,13 @@ For detailed documentation how to use the logger API check the http://www.slf4j. NOTE: In case you are using https://github.com/devonfw/ide[devonfw-ide] and Eclipse you can just type `LOG` and hit `[ctrl][space]` to insert the code pattern including the imports into your class. === Lombok + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In case you are using link:guide-lombok.asciidoc[Lombok], you can simply use the https://projectlombok.org/api/lombok/extern/slf4j/Slf4j.html[`@Slf4j`] annotation in your class. This causes Lombok to generate the logger instance for you. == Log-Levels + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. 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. @@ -76,16 +82,22 @@ This helps for better maintenance and operation of the systems. Exceptions (with their stack trace) should only be logged on `FATAL` or `ERROR` level. For business exceptions typically a `WARNING` including the message of the exception is sufficient. === Configuration of Logback + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The configuration of logback happens via the `logback.xml` file that you should place into `src/main/resources` of your app. For details consult the http://logback.qos.ch/manual/configuration.html[logback configuration manual]. NOTE: Logback also allows to overrule the configuration with a `logback-test.xml` file that you may put into `src/test/resources` or into a test-dependency. === Configuration in Quarkus + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The are several options you can set in the `application.properties` file to configure the behaviour of the logger in Quarkus. For a detailed overview, see the corresponding part of the https://quarkus.io/guides/logging#runtime-configuration[Quarkus guide]. == JSON-logging +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For easy integration with link:guide-log-monitoring.asciidoc[log-monitoring], we recommend that your app logs to `standard out` in JSON following https://jsonlines.org/[JSON Lines]. In Spring applications, this can be achieved via https://github.com/logstash/logstash-logback-encoder[logstash-logback-encoder] (see xref:dependencies[dependencies]). In Quarkus, it can be easily achieved using the https://github.com/quarkusio/quarkus/tree/main/extensions/logging-json[quarkus-logging-json] extension (see https://quarkus.io/guides/logging#json-logging[here] for more details). @@ -108,6 +120,8 @@ This will produce log-lines with the following format (example formatted for rea === Adding custom values to JSON log with Logstash +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The JSON encoder even supports logging custom properties for your link:guide-log-monitoring.asciidoc[log-monitoring]. The _trick_ is to use the class `net.logstash.logback.argument.StructuredArguments` for adding the arguments to you log message, e.g. @@ -135,11 +149,15 @@ As you can quickly see besides the human readable `message` you also have the st == Classic log-files +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + NOTE: **In devon4j, we strongly recommend using JSON logging instead of classic log files. The following section refers only to devon4j Spring applications that use Logback.** Even though we do not recommend anymore to write classical log-files to the local disc, here you can still find our approach for it. === Maven-Integration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In the `pom.xml` of your application add this dependency: [source,xml] ---- @@ -186,6 +204,8 @@ log.dir=../logs/ ---- === Log Files + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The classical approach uses the following log files: * *Error Log*: Includes log entries to detect errors. @@ -212,6 +232,8 @@ Error log from +mywebserver01+ at application +myapp+ at 16th September 2013 9pm === Output format +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We use the following output format for all log entries to ensure that searching and filtering of log entries work consistent for all logfiles: ``` @@ -233,6 +255,8 @@ Example: NOTE: When using devon4j-logging, this format is used by default. To achieve this format in Quarkus, set `quarkus.log.console.format=[D: %d] [P: %p] [C: %X] [T: %t] [L: %c] [M: %m]%n` in your properties. === Correlation ID + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In order to correlate separate HTTP requests to services belonging to the same user / session, we provide a servlet filter called `DiagnosticContextFilter`. This filter takes a provided correlation ID from the HTTP header `X-Correlation-Id`. If none was found, it will generate a new correlation id as `UUID`. @@ -241,5 +265,7 @@ Therefore, it will then be included to any log message of the current request (t Further concepts such as link:guide-service-client.asciidoc[service invocations] will pass this correlation ID to subsequent calls in the application landscape. Hence you can find all log messages related to an initial request simply via the correlation ID even in highly distributed systems. === Security + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In order to prevent https://owasp.org/www-community/attacks/Log_Injection[log forging] attacks you can simply use the suggested xref:json-logging[JSON logging] format. Otherwise you can use `com.devonfw.module.logging.common.impl.SingleLinePatternLayout` as demonstrated https://github.com/devonfw/devon4j/blob/master/modules/logging/src/main/resources/com/devonfw/logging/logback/appender-file-warn.xml[here] in order to prevent such attacks. diff --git a/documentation/guide-logic-layer.asciidoc b/documentation/guide-logic-layer.asciidoc index ca51f0b8..5da6fd94 100644 --- a/documentation/guide-logic-layer.asciidoc +++ b/documentation/guide-logic-layer.asciidoc @@ -1,18 +1,18 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Logic Layer +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The logic layer is the heart of the application and contains the main business logic. According to our link:architecture.asciidoc#business-architecture[business architecture], we divide an application into link:guide-component.asciidoc[components]. For each component, the logic layer defines different link:guide-usecase.asciidoc[use-cases]. Another approach is to define a link:guide-component-facade.asciidoc[component-facade], which we do not recommend for future application. Especially for quarkus application, we want to simplify things and highly suggest omitting component-facade completely and using use-cases only. It is very important that you follow the links to understand the concept of use-case in order to properly implement your business logic. == Responsibility + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The logic layer is responsible to implement the business logic according to the specified functional demands and requirements. Therefore, it creates the actual value of the application. The logic layer is responsible for invoking business logic in external systems. The following additional aspects are also included in its responsibility: @@ -22,9 +22,13 @@ The following additional aspects are also included in its responsibility: * link:guide-transactions.asciidoc[transaction-handling] (in addition to link:guide-service-layer.asciidoc[service layer]). == Security + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The logic layer is the heart of the application. It is also responsible for authorization and hence security is important in this current case. Every method exposed in an interface needs to be annotated with an authorization check, stating what role(s) a caller must provide in order to be allowed to make the call. The authorization concept is described link:guide-access-control.asciidoc#authorization[here]. === Direct Object References + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A security threat are https://www.owasp.org/index.php/Top_10_2013-A4-Insecure_Direct_Object_References[Insecure Direct Object References]. This simply gives you two options: * avoid direct object references diff --git a/documentation/guide-lombok.asciidoc b/documentation/guide-lombok.asciidoc index 4e39861a..56bd25a0 100644 --- a/documentation/guide-lombok.asciidoc +++ b/documentation/guide-lombok.asciidoc @@ -1,16 +1,16 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Lombok +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + https://projectlombok.org/[Lombok] is a library that works with an annotation processor and will generate code for you to save you some time and reduce the amount of boilerplate code in your project. Lombok can generate getter and setter, equals methods, automate your logging variables for your classes, and more. Follow the https://projectlombok.org/features/all[list of all the features] provided by Lombok to get an overview. == Lombok Dependency + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. To get access to the Lombok library just add the following dependency to the POM.xml. The Lombok dependency: @@ -25,6 +25,8 @@ The Lombok dependency: To get Lombok working with your current IDE you should also install the Lombok addon. Follow the https://projectlombok.org/setup/eclipse[Eclipse installation guide], there are also guides for other supported IDEs. == Lombok with Mapstruct + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. MapStruct takes advantage of generated getters, setters, and constructors from Lombok and uses them to generate the mapper implementations. Lombok is also an annotation processor and since version 1.18.14 both frameworks are working together. Just add the `lombok-mapstruct-binding` to your POM.xml. @@ -63,6 +65,8 @@ The Lombok annotation processor and the `lombok-mapstruct-binding` In our https://github.com/devonfw-sample/devon4quarkus-reference[quarkus reference project] you can get a look into the usage of both frameworks. == Lombok Usage + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Lombok can be used like any other annotation processor and will be shown in the simple example below to generate getter and setter for a _Product_ Entity. [source, java] diff --git a/documentation/guide-microservice.asciidoc b/documentation/guide-microservice.asciidoc index 001832a2..8867c9f5 100644 --- a/documentation/guide-microservice.asciidoc +++ b/documentation/guide-microservice.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Microservices in devonfw +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The Microservices architecture is an approach for application development based on a series of _small_ services grouped under a business domain. Each individual service runs autonomously and communicating with each other through their APIs. That independence between the different services allows to manage (upgrade, fix, deploy, etc.) each one without affecting the rest of the system's services. In addition to that the microservices architecture allows to scale specific services when facing an increment of the requests, so the applications based on microservices are more flexible and stable, and can be adapted quickly to demand changes. However, this new approach, developing apps based on microservices, presents some downsides. diff --git a/documentation/guide-migration-oasp3-to-devon3.1.asciidoc b/documentation/guide-migration-oasp3-to-devon3.1.asciidoc index 1a7c804b..204a26a0 100644 --- a/documentation/guide-migration-oasp3-to-devon3.1.asciidoc +++ b/documentation/guide-migration-oasp3-to-devon3.1.asciidoc @@ -1,9 +1,7 @@ -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Migration Guide from oasp 3.0.0 to devon4j 3.1.0 migration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + - https://github.com/devonfw/devonfw-guide/blob/master/general/devcon-command-reference.asciidoc#devon4j-migrate[Automatic migration] with devcon doesn't work with parent pom's; you need to migrate every single subproject on it's own. - If your subproject's don't contain the old oasp4j or devon4j version number you have to copy your parent pom file into your child pom files and then use the migrate command. - use the https://github.com/devonfw/devonfw-guide/blob/master/general/devcon-command-reference.asciidoc#devon4j-migrate[devon4j migation command] @@ -13,6 +11,8 @@ in the child pom file. == JsonDeserializer: +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + 1. Change the super class from AbstractJsonDeserializer to JsonDeserializer 2. Implement unimplemented methods or change the methode signatur from Pageable deserializeNode(JsonNode node) to Pageable deserialize(JsonParser p, DeserializationContext context) 3. To get the JsonNode you need to use the following methods with the JsonParser p: JsonNode node = p.getCodec().readTree(p); @@ -20,6 +20,8 @@ in the child pom file. == QueryUtil update +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + whereString() (StringSearchConfigTo) method or similar: 1. Check the parameter type with attetion on the source of the used class (the classes may have the same name but the one from oasp4j is obsolete) @@ -28,6 +30,8 @@ devon4j (for example import com.devonfw.module.beanmapping.common.api.BeanMapper == logback.xml file +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + 1. There maximum three chnages that needed to be done in the logback.xml file 2. Change the logging properties tag from `` to `` @@ -37,16 +41,22 @@ devon4j (for example import com.devonfw.module.beanmapping.common.api.BeanMapper == OaspPackage: +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + If you use the OaspPackage class you can replace it with the Devon4jPackage class == AbstractLogic +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + 1. You can replace all net.sf.mmm.util imports with the appropriate com.devonfw.module imports. For example "import net.sf.mmm.util.entity.api.GenericEntity" to "import com.devonfw.module.basic.common.api.entity.GenericEntity" 2. Except the TransferObject and the AbstractTransferObject. These are replaced with the denvonfw AbstractTo. Example: "import net.sf.mmm.util.transferobject.api.AbstractTransferObject" or "import net.sf.mmm.util.transferobject.api.TransferObject" to "import com.devonfw.module.basic.common.api.to.AbstractTo". == BeanDozerConfig +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + . Change the @ComponentScan annotation from `@ComponentScan(basePackages = { "io.oasp.module.beanmapping" })` to `@ComponentScan(basePackages = { "com.devonfw.module.beanmapping" })`. . Now you have to create a variable `DOZER_MAPPING_XML` with following content: `static final String DOZER_MAPPING_XML = "config/app/common/dozer-mapping.xml"`. . Then you create an list beanMappings where you add the variable created in step 2. @@ -61,6 +71,8 @@ https://github.com/DozerMapper/dozer/blob/master/docs/asciidoc/migration/v63-to- == pom.xml +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In the pom.xml file you have to do some manuall changes. You need to change all oasp dependencies to denvonfw dependencies. Here are some examples: 1. from @@ -271,11 +283,15 @@ In the pom.xml file you have to do some manuall changes. You need to change all == MutableGenericEntity +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + If you use the MutableGenericEntity<> class you have to change it to the PersistenceEntity<> class. Change the import "net.sf.mmm.util.entity.api.MutableGenericEntity" to "import com.devonfw.module.basic.common.api.entity.PersistenceEntity". == CompositeTo +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + If you use the CompositeTo class you should now use the AbstractTo class. Just change the import from "import net.sf.mmm.util.transferobject.api.CompositeTo" to "import com.devonfw.module.basic.common.api.to.AbstractTo". diff --git a/documentation/guide-migration-spring-quarkus.asciidoc b/documentation/guide-migration-spring-quarkus.asciidoc index c041d5ee..583e3ca7 100644 --- a/documentation/guide-migration-spring-quarkus.asciidoc +++ b/documentation/guide-migration-spring-quarkus.asciidoc @@ -1,32 +1,38 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Migrate from Spring to Quarkus +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This guide will cover the migration process of a Spring application to a Quarkus application. There are already articles about migrating from Spring to Quarkus (e.g. https://developers.redhat.com/blog/2020/04/10/migrating-a-spring-boot-microservices-application-to-quarkus, https://dzone.com/articles/migrating-a-spring-boot-application-to-quarkus-cha). This guide will focus more on the devon4j specific aspects. We assume that a working Spring application exists, built in the link:guide-structure-classic.asciidoc[classic devon4j specific way] (e.g. https://github.com/devonfw/jump-the-queue/tree/master/java/jtqj[Jump The Queue] or https://github.com/devonfw/my-thai-star[My Thai Star]). == Create the Quarkus application +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We start with an empty Quarkus project. You can create the project with Maven on the command line or use the https://code.quarkus.io/[online generator]. The advantage of the online generator is that you have a pre-selection of dependencies to use in your project. For starters, let's select the basic dependencies required to develop a REST service with database connectivity (you can use one of the links in the link:quarkus/quarkus-template.asciidoc[Quarkus template guide]): __RESTEasy JAX-RS, RESTEasy Jackson, Hibernate ORM, Spring Data JPA API, JDBC Driver (choose the type of database you need), Flyway (if you have database migration schemas), SmallRye Health (optional for Health Monitoring)__ The list does not include all required dependencies. We will add more dependencies to the project later. For now, generate the application with these dependencies. === Migration Toolkit from Red Hat + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Red Hat provides a migration toolkit (https://developers.redhat.com/products/mta/overview[MTA, Migration Toolkit for Applications]), that supports migration of a Spring to a Quarkus application. There are several versions of this toolkit (e.g., a web console, a Maven plugin, or an IDE plugin). The MTA analyzes your existing application and generates a report with hints and instructions for migrating from Spring to Quarkus. For example, it gives you an indication of which dependencies are not supported in your project for a Quarkus application and which dependencies you need to swap them with. The analysis is rule-based, and you can also add your own rules that will be checked during analysis. == Entities +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + There is nothing special to consider when creating the entities. In most cases, you can simply take the code from your Spring application and use it for your Quarkus application. Usually, the entities extend a superclass `ApplicationPersistenceEntity` containing, for example, the `id` property. You can also take this class from your Spring application and reuse it. == Transfer objects +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The next step is to create the appropriate transfer objects for the entities. In a devon4j Spring application, we would use CobiGen to create these classes. Since CobiGen is not usable for this purpose in Quarkus applications yet, we have to create the classes manually. First, we create some abstract base classes for the search criteria and DTO classes. Normally, these would also be created by CobiGen. @@ -75,6 +81,8 @@ Now you can create your transfer objects. Most of the code of the transfer objec == Data Access Layer +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In devon4j, we propose to use link:guide-repository.asciidoc[Spring Data JPA] to build the data access layer using repositories and Querydsl to build link:guide-jpa-query.asciidoc#dynamic-queries[dynamic queries]. We will also use this approach for Quarkus applications, but we need to change the implementation because the devon4j modules are based on reflection, which is not suitable for Quarkus. In Quarkus we will use Querydsl using code generation. So for this layer, more changes are required and we can't just take the existing code. @@ -139,12 +147,16 @@ quarkus.datasource.password=... == Logic Layer +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For the logic layer, devon4j uses a link:guide-usecase.asciidoc[use-case approach]. You can reuse the use case interfaces from the api module of the Spring application. Again, make sure to rename the transfer objects. Create the appropriate class that implements the interface. Follow the link:guide-usecase.asciidoc#implementation[implementation section] of the use-case guide to implement the methods. For mapping the entities to the corresponding transfer objects, see the next section. == Mapping +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For bean mapping, we need to use a completely different approach in the Quarkus application than in the Spring application. For Quarkus, we use MapStruct, which creates the mapper at build time rather than at runtime using reflection. Add the following dependencies to your pom.xml. .**pom.xml** @@ -181,6 +193,8 @@ Inject the mapper into your use-case implementation and simply use the methods. == Service Layer +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For the implementation of the service layer, we use the link:guide-rest#jax-rs[JAX-RS] for both Quarkus and Spring applications to create the REST services. Classic devon4j Spring applications rely on Apache CFX as the implemention of JAX-RS. For Quarkus, we use RESTEasy. Since both are implementations of JAX-RS, much of the Spring application code can be reused. @@ -211,6 +225,8 @@ public class YourComponentRestService { == Summary +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + As you have seen, some parts hardly differ when migrating a Spring application to a Quarkus application, while other parts differ more. The above sections describe the parts needed for simple applications that provide REST services with a data access layer. If you add more functionality, more customization and other frameworks, dependencies may be required. If that is the case, take a look at the corresponding guide on the topic in the devon4j documentation or check if there is a tutorial on the official https://quarkus.io/guides/[Quarkus website]. diff --git a/documentation/guide-monitoring.asciidoc b/documentation/guide-monitoring.asciidoc index e81e18a0..d4b40d67 100644 --- a/documentation/guide-monitoring.asciidoc +++ b/documentation/guide-monitoring.asciidoc @@ -1,12 +1,10 @@ :toc: toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Monitoring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For monitoring a complex application landscape it is crucial to have an exact overview which applications are up and running and which are not and why. In devonfw we only focus on topics which are most important when developing production-ready applications. On a high level view we strongly suggest to separate the application to be monitored from the `monitoring system` itself. @@ -18,6 +16,8 @@ Instead please search and find the products that fit best for your requirements == Types of monitoring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + As monitoring coveres a lot of different aspects we separate the following types of monitoring and according data: * *link:guide-log-monitoring.asciidoc[Log-monitoring]* + @@ -31,6 +31,8 @@ is about measuring performance and tracing down performance issues. == Health-Check +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The idea of a health check is to prodvide monitoring data about the current health status of your application. This allows to integrate this specific data into the monitoring system used for your IT landscape. In order to keep the monitoring simple and easy to integreate consider using the following best practices: diff --git a/documentation/guide-openapi.asciidoc b/documentation/guide-openapi.asciidoc index 70aa3ffe..d3482d6c 100644 --- a/documentation/guide-openapi.asciidoc +++ b/documentation/guide-openapi.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = OpenAPI +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The link:https://spec.openapis.org/oas/latest.html[OpenAPI Specification (OAS)] defines a standard for describing RESTful web services in a machine- and human-readable format. OpenAPI allows REST APIs to be defined in a uniform manner. Technically, an OpenAPI document is written in YAML or JSON format. The specification defines the structure of a REST API by describing attributes such as path information, response codes, and return types. Some examples can be found link:https://github.com/OAI/OpenAPI-Specification/tree/main/examples/v3.0[here]. Apart from documenting the API, this schema then also acts as a contract between provider and consumers, guaranteeing interoperability between various technologies. @@ -16,13 +14,19 @@ The most common tool is the link:https://swagger.io/tools/swagger-ui/[Swagger UI [NOTE] ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Swagger and OpenAPI: Swagger is a former specification, based on which the OpenAPI was created. Swagger 2.0 is still commonly used for describing APIs. OpenAPI is an open-source collaboration and it started from version 3.0.0(semver) ==== +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + There are many tools that work with OpenAPI: code generators, documentation tools, validators etc. == OpenAPI generation +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + There are several extensions you can use in your project to automatically generate the OpenAPI specifications and Swagger UI from your REST API (code-first approach). devon4j recommends the following two extensions/plugins to use: * Smallrye OpenAPI extension @@ -30,6 +34,8 @@ There are several extensions you can use in your project to automatically genera === Smallrye OpenAPI +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus provides OpenAPI support through Smallrye OpenAPI extension: [source,xml] @@ -49,12 +55,18 @@ More information for this can be found link:https://quarkus.io/blog/openapi-for- [NOTE] ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Quarkus recommends using this extension and you can document your APIs in great detail by using the MicroProfile annotations. The downside to this is that using these annotations will blow up your code and you will have some duplicate information in it. If you don't want to specify the REST API again with all this annotation based information, we also recommend taking a look at the ServicedocGen Maven plugin for your Quarkus applications when implementing JAX-RS APIs. ==== +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === ServicedocGen Maven Plugin +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The link:https://github.com/mojohaus/servicedocgen-maven-plugin[ServicedocGen maven plugin] can be used within both Spring and Quarkus applications. It works a bit different then the Smallrye extensions mentioned above. The plugin analysis the REST API and it's JavaDoc and then generate the OpenAPI specification and the Swagger UI as static files. So no Swagger or MicroProfile annotations have to be added. diff --git a/documentation/guide-queueing.asciidoc b/documentation/guide-queueing.asciidoc index 3373d784..73c9c2cf 100644 --- a/documentation/guide-queueing.asciidoc +++ b/documentation/guide-queueing.asciidoc @@ -1,24 +1,30 @@ :toc: toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = JMS +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == Introduction +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + TODO == Sending Messages +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + TODO == Receiving Messages +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + TODO == Using JMS Broker +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + TODO \ No newline at end of file diff --git a/documentation/guide-repository.asciidoc b/documentation/guide-repository.asciidoc index f8f87764..f593178f 100644 --- a/documentation/guide-repository.asciidoc +++ b/documentation/guide-repository.asciidoc @@ -1,14 +1,14 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Spring Data + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. https://projects.spring.io/spring-data-jpa/[Spring Data JPA] is supported by both Spring and Quarkus. However, in Quarkus this approach still has some limitations. For detailed information, see the official https://quarkus.io/guides/spring-data-jpa[Quarkus Spring Data guide]. == Motivation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The benefits of Spring Data are (for examples and explanations see next sections): * All you need is one single repository interface for each entity. No need for a separate implementation or other code artifacts like XML descriptors, `NamedQueries` class, etc. @@ -18,6 +18,8 @@ The benefits of Spring Data are (for examples and explanations see next sections * Still you have the freedom to write custom implementations via default methods within the repository interface (e.g. for dynamic queries). == Dependency + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In case you want to switch to or add Spring Data support to your Spring or Quarkus application, all you need is to add the respective maven dependency: .**spring** @@ -39,6 +41,8 @@ In case you want to switch to or add Spring Data support to your Spring or Quark -------- == Repository + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For each entity `«Entity»Entity` an interface is created with the name `«Entity»Repository` extending https://docs.spring.io/spring-data/jpa/docs/current/api/org/springframework/data/jpa/repository/JpaRepository.html[JpaRepository]. Such repository is the analogy to a link:guide-dao.asciidoc[Data-Access-Object (DAO)] used in the classic approach or when Spring Data is not an option. @@ -54,9 +58,13 @@ The Spring Data repository provides some basic implementations for accessing dat == Custom method implementation +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In addition, repositories can be enriched with additional functionality, e.g. to add QueryDSL functionality or to override the default implementations, by using so called repository fragments: === Example + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The following example shows how to write such a repository: .**Repository** @@ -119,10 +127,14 @@ NOTE: In Quarkus, native and named queries via the `@Query` annotation are curre === Integration of Spring Data in devon4j-spring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For Spring applications, devon4j offers a proprietary solution that integrates seamlessly with QueryDSL and uses default methods instead of the fragment approach. A separate guide for this can be found link:spring/guide-devon4j-spring-repository.asciidoc[here]. === Custom methods without fragment approach +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The fragment approach is a bit laborious, as three types (repository interface, fragment interface and fragment implementation) are always needed to implement custom methods. We cannot simply use default methods within the repository because we cannot inject the `EntityManager` directly into the repository interface. @@ -175,11 +187,15 @@ public interface ProductRepository extends JpaRepository, G ---- == Drawbacks + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Spring Data also has some drawbacks: * Some kind of magic behind the scenes that are not so easy to understand. So in case you want to extend all your repositories without providing the implementation via a default method in a parent repository interface you need to deep-dive into Spring Data. We assume that you do not need that and hope what Spring Data and devon already provides out-of-the-box is already sufficient. * The Spring Data magic also includes guessing the query from the method name. This is not easy to understand and especially to debug. Our suggestion is not to use this feature at all and either provide a `@Query` annotation or an implementation via default method. == Limitations in Quarkus + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. * Native and named queries are not supported using `@Query` annotation. You will receive something like: __Build step io.quarkus.spring.data.deployment.SpringDataJPAProcessor#build threw an exception: java.lang.IllegalArgumentException: Attribute nativeQuery of @Query is currently not supported__ * Customizing the base repository for all repository interfaces in the code base, which is done in Spring Data by registering a class the extends `SimpleJpaRepository` diff --git a/documentation/guide-rest-philosophy.asciidoc b/documentation/guide-rest-philosophy.asciidoc index b4036673..0b259feb 100644 --- a/documentation/guide-rest-philosophy.asciidoc +++ b/documentation/guide-rest-philosophy.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = REST Philosophy +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + REST and RESTful often implies very strict and specific rules and conventions. However different people will often have different opinions of such rules. We learned that this leads to "religious discussions" (starting from `PUT` vs. `POST` and IDs in path vs. payload up to Hypermedia and https://en.wikipedia.org/wiki/HATEOAS[HATEOAS]). @@ -56,6 +54,8 @@ Please consider these guidelines and rationales: * Please also note that for (large) bulk deletions you may be forced to used `POST` instead of `DELETE` as according to the HTTP standard `DELETE` must not have payload and URLs are limited in length. == Metadata + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. devonfw has support for the following metadata in REST service invocations: [options="header"] @@ -69,6 +69,8 @@ The protocol to communicate these validation errors is described in xref:rest-ex |======= == Recommendations for REST requests and responses + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The devonfw proposes, for simplicity, a deviation from the common REST pattern: * Using `POST` for updates (instead of `PUT`) @@ -80,6 +82,8 @@ This use of REST will lead to simpler code both on client and on server. We disc The following table specifies how to use the HTTP methods (verbs) for collection and element URIs properly (see http://en.wikipedia.org/wiki/Representational_State_Transfer#Applied_to_web_services[wikipedia]). === Unparameterized loading of a single resource + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. * *HTTP Method*: `GET` * *URL example*: `/services/rest/productmanagement/v1/product/123` @@ -97,6 +101,8 @@ The response contains the resource in JSON format, using a JSON object at the to ---- === Unparameterized loading of a collection of resources + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. * *HTTP Method*: `GET` * *URL example*: `/services/rest/productmanagement/v1/product` @@ -123,6 +129,8 @@ The response contains the collection in JSON format, using a JSON object at the ---- === Saving a resource + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. * *HTTP Method*: `POST` * *URL example*: `/services/rest/productmanagement/v1/product` @@ -134,6 +142,8 @@ If saving was unsuccessful, refer below for the format to return errors to the c === Parameterized loading of a resource + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. * *HTTP Method*: `POST` * *URL example*: `/services/rest/productmanagement/v1/product/search` @@ -208,11 +218,15 @@ With the equivalent code required if doing it the RESTful way by issuing a `GET` ==== Pagination details +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The client can choose to request a count of the total size of the collection, for example to calculate the total number of available pages. It does so, by specifying the `pagination.total` property with a value of `true`. The service is free to honour this request. If it chooses to do so, it returns the total count as the `pagination.total` property in the response. === Deletion of a resource + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. * *HTTP Method*: `DELETE` * *URL example*: `/services/rest/productmanagement/v1/product/123` @@ -220,6 +234,8 @@ For deletion of a single resource, embed the `identifier` of the resource in the === Error results +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The general format for returning an error to the client is as follows: [source,javascript] @@ -250,9 +266,13 @@ If the error is caused by a failed validation of the entity, the above format is ---- == REST Media Types + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The payload of a REST service can be in any format as REST by itself does not specify this. The most established ones that the devonfw recommends are link:guide-xml.asciidoc[XML] and link:guide-json.asciidoc[JSON]. Follow these links for further details and guidance how to use them properly. `JAX-RS` and `CXF` properly support these formats (`MediaType.APPLICATION_JSON` and `MediaType.APPLICATION_XML` can be specified for `@Produces` or `@Consumes`). Try to decide for a single format for all services if possible and NEVER mix different formats in a service. == REST Testing + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For testing REST services in general consult the link:guide-testing.asciidoc[testing guide]. For manual testing REST services there are browser plugins: @@ -261,12 +281,18 @@ For manual testing REST services there are browser plugins: * Chrome: http://www.getpostman.com/[postman] (https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo[advanced-rest-client]) == Security + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Your services are the major entry point to your application. Hence security considerations are important here. === CSRF + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A common security threat is https://www.owasp.org/index.php/Top_10_2013-A8-Cross-Site_Request_Forgery_(CSRF)[CSRF] for REST services. Therefore all REST operations that are performing modifications (PUT, POST, DELETE, etc. - all except GET) have to be secured against CSRF attacks. See link:guide-csrf.asciidoc[CSRF] how to do this. === JSON top-level arrays + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. OWASP earlier suggested to never return JSON arrays at the top-level, to prevent attacks without rationale. We digged deep and found https://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx/[anatomy-of-a-subtle-json-vulnerability]. To sum it up the attack is many years old and does not work in any recent or relevant browser. diff --git a/documentation/guide-rest.asciidoc b/documentation/guide-rest.asciidoc index 414978a5..82a74e91 100644 --- a/documentation/guide-rest.asciidoc +++ b/documentation/guide-rest.asciidoc @@ -1,16 +1,16 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = REST + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. REST (https://en.wikipedia.org/wiki/Representational_state_transfer[REpresentational State Transfer]) is an inter-operable protocol for link:guide-service-layer.asciidoc[services] that is more lightweight than link:guide-soap.asciidoc[SOAP]. However, it is no real standard and can cause confusion (see link:https://github.com/devonfw/devon4j/blob/master/documentation/guide-rest-philosophy.asciidoc[REST philosophy]). Therefore we define best practices here to guide you. == URLs + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. URLs are not case sensitive. Hence, we follow the best practice to use only lower-case-letters-with-hyphen-to-separate-words. For operations in REST we distinguish the following types of URLs: @@ -24,6 +24,8 @@ For business operations (processing, calculation, advanced search, etc.) we simp Then we can `POST` the input for the business operation and get the result back. Example: `\https://mydomain.com/myapp/services/rest/mycomponent/v1/myentity/search` == HTTP Methods + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The following table defines the HTTP methods (verbs) and their meaning: .Usage of HTTP methods @@ -41,6 +43,8 @@ Please also note that for (large) bulk deletions you may be forced to used `POST For general recommendations on HTTP methods for collection and element URLs see http://en.wikipedia.org/wiki/Representational_State_Transfer#Applied_to_web_services[REST@wikipedia]. == HTTP Status Codes + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Further we define how to use the HTTP status codes for REST services properly. In general the 4xx codes correspond to an error on the client side and the 5xx codes to an error on the server side. .Usage of HTTP status codes @@ -57,6 +61,8 @@ Further we define how to use the HTTP status codes for REST services properly. I |======================= == JAX-RS + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For implementing REST services we use the https://jax-rs-spec.java.net/[JAX-RS] standard. As payload encoding we recommend link:guide-json.asciidoc[JSON] bindings using http://wiki.fasterxml.com/JacksonHome[Jackson]. To implement a REST service you simply add JAX-RS annotations. @@ -87,6 +93,8 @@ NOTE: With JAX-RS it is important to make sure that each service method is annot === Service-Interface +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + You may also separate API and implementation in case you want to reuse the API for link:guide-service-client.asciidoc[service-client]: [source,java] @@ -115,11 +123,15 @@ public class ImagemanagementRestServiceImpl implements ImagemanagementRestServic -------- === JAX-RS Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Starting from CXF 3.0.0 it is possible to enable the auto-discovery of JAX-RS roots. When the JAX-RS server is instantiated, all the scanned root and provider beans (beans annotated with `javax.ws.rs.Path` and `javax.ws.rs.ext.Provider`) are configured. === REST Exception Handling + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For exceptions, a service needs to have an exception facade that catches all exceptions and handles them by writing proper log messages and mapping them to a HTTP response with an corresponding xref:http-status-codes[HTTP status code]. For this, devon4j provides a generic solution via `RestServiceExceptionFacade` that you can use within your Spring applications. You need to follow the link:guide-exceptions.asciidoc[exception guide] in order for it to work out of the box because the facade needs to be able to distinguish between business and technical exceptions. To implement a generic exception facade in Quarkus, follow the link:quarkus/guide-exception-handling.asciidoc[Quarkus exception guide]. @@ -138,6 +150,8 @@ The general format for returning an error to the client is as follows: ---- === Pagination details + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We recommend to use link:guide-repository.asciidoc[spring-data repositories] for database access that already comes with pagination support. Therefore, when performing a search, you can include a https://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data/domain/Pageable.html[Pageable] object. Here is a JSON example for it: @@ -164,6 +178,8 @@ Via the `pageable` property the client gets back the `Pageable` properties from The actual hits for the current page are returned as array in the `content` property. == REST Testing + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For testing REST services in general consult the link:guide-testing.asciidoc[testing guide]. For manual testing REST services there are browser plugins: @@ -172,12 +188,18 @@ For manual testing REST services there are browser plugins: * Chrome: http://www.getpostman.com/[postman] (https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo[advanced-rest-client]) == Security + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Your services are the major entry point to your application. Hence security considerations are important here. === CSRF + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A common security threat is https://www.owasp.org/index.php/Top_10_2013-A8-Cross-Site_Request_Forgery_(CSRF)[CSRF] for REST services. Therefore all REST operations that are performing modifications (PUT, POST, DELETE, etc. - all except GET) have to be secured against CSRF attacks. See link:guide-csrf.asciidoc[CSRF] how to do this. === JSON top-level arrays + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. OWASP earlier suggested to never return JSON arrays at the top-level, to prevent attacks without rationale. We digged deep and found https://haacked.com/archive/2008/11/20/anatomy-of-a-subtle-json-vulnerability.aspx/[anatomy-of-a-subtle-json-vulnerability]. To sum it up the attack is many years old and does not work in any recent or relevant browser. diff --git a/documentation/guide-scm.asciidoc b/documentation/guide-scm.asciidoc index 554bb263..9d30268a 100644 --- a/documentation/guide-scm.asciidoc +++ b/documentation/guide-scm.asciidoc @@ -1,25 +1,33 @@ :toc: toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Software-Configuration-Management +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + TODO == Build-Management + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. TODO === Continuous-Integration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. TODO == Issue-Management + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. TODO == Release-Management + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. TODO == Deployment-Management + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. TODO \ No newline at end of file diff --git a/documentation/guide-security.asciidoc b/documentation/guide-security.asciidoc index db1974d4..57f5df50 100644 --- a/documentation/guide-security.asciidoc +++ b/documentation/guide-security.asciidoc @@ -1,17 +1,17 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Security + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. //Fixed Typo Security is todays most important cross-cutting concern of an application and an enterprise IT-landscape. We seriously care about security and give you detailed guides to prevent pitfalls, vulnerabilities, and other disasters. While many mistakes can be avoided by following our guidelines you still have to consider security and think about it in your design and implementation. The security guide will not only automatically prevent you from any harm, but will provide you hints and best practices already used in different software products. An important aspect of security is proper authentication and authorization as described in link:guide-access-control.asciidoc[access-control]. In the following we discuss about potential vulnerabilities and protection to prevent them. == Vulnerabilities and Protection + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Independent from classical authentication and authorization mechanisms there are many common pitfalls that can lead to vulnerabilities and security issues in your application such as XSS, CSRF, SQL-injection, log-forging, etc. A good source of information about this is the https://www.owasp.org[OWASP]. We address these common threats individually in _security_ sections of our technological guides as a concrete solution to prevent an attack typically depends on the according technology. The following table illustrates common threats and contains links to the solutions and protection-mechanisms provided by the devonfw: @@ -78,12 +78,18 @@ We address these common threats individually in _security_ sections of our techn == Advanced Security +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + While OWASP Top 10 covers the basic aspects of application security, there are advanced standards such as `AVS`. In devonfw we address this in the https://github.com/devonfw/security/wiki[ Application Security Quick Solution Guide]. == Tools + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. === Dependency Check + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. To address the thread `Using Components with Known Vulnerabilities` we recomment to use https://www.owasp.org/index.php/OWASP_Dependency_Check[OWASP dependency check] that ships with a maven plugin and can analyze your dependencies for known https://en.wikipedia.org/wiki/Common_Vulnerabilities_and_Exposures[CVE]s. In order to run this check, you can simply call this command on any maven project: [source,bash] @@ -102,6 +108,8 @@ This does not run by default as it causes some overhead for the build performanc After the dependency check is performed, you will find the results in `target/dependency-check-report.html` of each module. The report will also be generated when the site is build (`mvn site`) even without the profile. === Penetration Testing + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For penetration testing (testing for vulnerabilities) of your web application, we recommend the following tools: * https://www.owasp.org/index.php/OWASP_Zed_Attack_Proxy_Project[ZAP] (OWASP Zed Attack Proxy Project) diff --git a/documentation/guide-service-client.asciidoc b/documentation/guide-service-client.asciidoc index a3b9289c..e1eb1eb2 100644 --- a/documentation/guide-service-client.asciidoc +++ b/documentation/guide-service-client.asciidoc @@ -2,19 +2,21 @@ :icons: font toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Service Client +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This guide is about consuming (calling) services from other applications (micro-services). For providing services, see the link:guide-service-layer.asciidoc[Service-Layer Guide]. Services can be consumed by the link:guide-client-layer.asciidoc[client] or the server. As the client is typically not written in Java, you should consult the according guide for your client technology. In case you want to call a service within your Java code, this guide is the right place to get help. == Motivation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Various solutions already exist for calling services, such as `RestTemplate` from spring or the JAX-RS client API. Furthermore, each and every service framework offers its own API as well. These solutions might be suitable for very small and simple projects (with one or two such invocations). However, with the trend of microservices, the invocation of a service becomes a very common use-case that occurs all over the place. You typically need a solution that is very easy to use but supports flexible configuration, adding headers for authentication, mapping of errors from the server, logging success/errors with duration for performance analysis, support for synchronous and asynchronous invocations, etc. This is exactly what this `devon4j` service-client solution brings to you. == Usage +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + *Spring* For Spring, follow the link:spring/guide-service-client-spring.asciidoc[Spring rest-client guide]. diff --git a/documentation/guide-service-layer.asciidoc b/documentation/guide-service-layer.asciidoc index 570ff96d..d4294b9e 100644 --- a/documentation/guide-service-layer.asciidoc +++ b/documentation/guide-service-layer.asciidoc @@ -1,16 +1,16 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Service Layer +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The service layer is responsible for exposing functionality made available by the link:guide-logic-layer.asciidoc[logical layer] to external consumers over a network via xref:protocol[technical protocols]. == Types of Services +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Before you start creating your services you should consider some general design aspects: * Do you want to create a https://en.wikipedia.org/wiki/Remote_procedure_call[RPC] service? @@ -25,6 +25,8 @@ For RPC a common choice is link:guide-rest.asciidoc[REST] but there are also int When it comes to messaging in Java the typical answer will be link:guide-jms.asciidoc[JMS]. However, a very promising alternative is link:guide-kafka.asciidoc[Kafka]. == Versioning + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For RPC services consumed by other applications we use versioning to prevent incompatibilities between applications when deploying updates. This is done by the following conventions: * We define a version number and prefix it with `v` (e.g. `v1`). @@ -34,9 +36,13 @@ For RPC services consumed by other applications we use versioning to prevent inc * For maintenance and simplicity, avoid keeping more than one previous version. == Interoperability + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For services that are consumed by clients with different technology, _interoperability_ is required. This is addressed by selecting the right protocol, following protocol-specific best practices and following our considerations especially _simplicity_. == Service Considerations + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The term _service_ is quite generic and therefore easily misunderstood. It is a unit exposing coherent functionality via a well-defined interface over a network. For the design of a service, we consider the following aspects: * *self-contained* + @@ -55,6 +61,8 @@ Process individual entities (for processing large sets of data, use a link:guide Avoid polymorphism, RPC methods with unique name per signature and no overloading, avoid attachments (consider separate download service), etc. == Security + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Your services are the major entry point to your application. Hence, security considerations are important here. See link:guide-rest.asciidoc#security[REST Security]. diff --git a/documentation/guide-service-versioning.asciidoc b/documentation/guide-service-versioning.asciidoc index d4fdcf84..f1ebda2b 100644 --- a/documentation/guide-service-versioning.asciidoc +++ b/documentation/guide-service-versioning.asciidoc @@ -1,15 +1,15 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Service-Versioning +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This guide describes the aspect and details about versioning of link:guide-service-layer.asciidoc[services] == Motivation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Why versioning of services? First of all, you should only care about this topic if you really have to. Service versioning is complex and requires effort (time and budget). The best way to avoid this is to be smart in the first place when designing the service API. Further, if you are creating services where the only consumer is e.g. the web-client that you deploy together with the consumed services then you can change your service without the overhead to create new service versions and keeping old service versions for compatibility. @@ -35,6 +35,8 @@ What changes do not cause incompatibilities? Even if you hit an indicator for incompatible changes you can still think about adding a new service operation instead of changing an existing one (and deprecating the old one). Be creative to simplify and avoid extra effort. == Procedure + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The procedure when rolling out incompatible changes is illustrated by the following example: [source] @@ -125,6 +127,8 @@ Now, also `App1` has been updated and deployed and it is using the new version ` Finally, version `v1` of the service `S` was removed from `App3` and the new release has been deployed. == Versioning Schema + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In general anything can be used to differentiate versions of a service. Possibilities are: * Code names (e.g. `Strawberry`, `Blueberry`, `Grapefruit`) @@ -137,6 +141,8 @@ As we are following the KISS principle (see link:architecture.asciidoc#key-princ We suggest to always add the version schema to the service URL to be prepared for service versioning even if service versioning is not (yet) actively used. For simplicity it is explicitly stated that you may even do incompatible changes to the current version (typically `v1`) of your service if you can update the according consumers within the same deployment. == Practice + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. So assuming you know that you have to do service versioning, the question is how to do it practically in the code. The approach for your devon4j project in case of code-first should be as described below: @@ -153,6 +159,8 @@ The approach for your devon4j project in case of code-first should be as describ * Finally, ensure that both the old service behaves as before as well as the new service works as planned. === Modularization + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For modularization, we also follow the KISS principle (see link:architecture.asciidoc#key-principles[key principles]): we suggest to have one `api` module per application that will contain the most recent version of your service and get released with every release-version of the application. The compatibility code with the versioned packages will be added to the `core` module and therefore is not exposed via the `api` module (because it has already been exposed in the previous release of the app). This way, you can always determine for sure which version of a service is used by another application just by its maven dependencies. diff --git a/documentation/guide-soap.asciidoc b/documentation/guide-soap.asciidoc index 7ab484ff..3074b8e6 100644 --- a/documentation/guide-soap.asciidoc +++ b/documentation/guide-soap.asciidoc @@ -1,15 +1,15 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = SOAP + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. https://en.wikipedia.org/wiki/SOAP[SOAP] is a common protocol for link:guide-service-layer.asciidoc[services] that is rather complex and heavy. It allows to build inter-operable and well specified services (see WSDL). SOAP is transport neutral what is not only an advantage. We strongly recommend to use HTTPS transport and ignore additional complex standards like WS-Security and use established HTTP-Standards such as RFC2617 (and RFC5280). //There is no SOAP example in our application -maybe keep this as a general example?- == JAX-WS + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For building web-services with Java we use the https://jcp.org/en/jsr/detail?id=224[JAX-WS] standard. There are two approaches: @@ -19,6 +19,8 @@ There are two approaches: Here is an example in case you define a code-first service. === Web-Service Interface + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We define a regular interface to define the API of the service and annotate it with JAX-WS annotations: [source,java] -------- @@ -34,6 +36,8 @@ public interface TablemanagmentWebService { === Web-Service Implementation +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + And here is a simple implementation of the service: [source,java] -------- @@ -51,9 +55,13 @@ public class TablemanagementWebServiceImpl implements TablemanagmentWebService { -------- == SOAP Custom Mapping + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In order to map custom link:guide-datatype.asciidoc[datatypes] or other types that do not follow the Java bean conventions, you need to write adapters for JAXB (see link:guide-xml.asciidoc[XML]). == SOAP Testing + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For testing SOAP services in general consult the link:guide-testing.asciidoc[testing guide]. For testing SOAP services manually we strongly recommend http://www.soapui.org/[SoapUI]. diff --git a/documentation/guide-sql.asciidoc b/documentation/guide-sql.asciidoc index 9399417b..23a167c5 100644 --- a/documentation/guide-sql.asciidoc +++ b/documentation/guide-sql.asciidoc @@ -1,22 +1,24 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = SQL +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For general guides on dealing or avoiding SQL, preventing SQL-injection, etc. you should study link:guide-domain-layer.asciidoc[domain layer]. == Naming Conventions +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Here we define naming conventions that you should follow whenever you write SQL files: * All SQL-Keywords in UPPER CASE * Indentation should be 2 spaces as suggested by devonfw for every format. === DDL + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The naming conventions for database constructs (tables, columns, triggers, constraints, etc.) should be aligned with your database product and their operators. However, when you have the freedom of choice and a modern case-sensitive database, you can simply use your code conventions also for database constructs to avoid explicitly mapping each and every property (e.g. `RestaurantTable` vs. `RESTAURANT_TABLE`). @@ -62,6 +64,8 @@ COMMENT ON TABLE RESTAURANT_ORDER IS 'An order and bill at the restaurant.'; ATTENTION: Please note that `TABLE` and `ORDER` are reserved keywords in SQL and you should avoid using such keywords to prevent problems. === Data + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For insert, update, delete, etc. of data SQL scripts should additionally follow these guidelines: * Inserts always with the same order of columns in blocks for each table. diff --git a/documentation/guide-structure-classic.asciidoc b/documentation/guide-structure-classic.asciidoc index bd6d88ce..2aa5fee4 100644 --- a/documentation/guide-structure-classic.asciidoc +++ b/documentation/guide-structure-classic.asciidoc @@ -1,18 +1,18 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Classic project structure +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In this section we describe the classic project structure as initially proposed for Java in devonfw. It is still valid and fully supported. However, if you want to start a new project, please consider using the link:guide-structure-modern.asciidoc[modern structure]. == Modules +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The structure of a `devon4j` application is divided into the following modules: * `api`: module containing the API of your application. The API contains the required artifacts to interact with your application via remote services. This can be link:guide-rest.asciidoc#jax-rs[REST service interfaces], link:guide-transferobject.asciidoc[transfer-objects] with their interfaces and link:guide-datatype.asciidoc[datatypes] but also https://www.openapis.org/[OpenAPI] or https://grpc.io/[gRPC] contracts. @@ -22,6 +22,8 @@ The structure of a `devon4j` application is divided into the following modules: == Deployment +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + [quote, Josh Long] ____ Make jar not war @@ -39,10 +41,14 @@ All you need to do in that case is to change the `packaging` in your `server/pom == Package Structure +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The package structure of your code inside `src/main/java` (and `src/test/java`) of your modules is described in our coding conventions in the sections link:coding-conventions.asciidoc#packages[packages]. A full mapping of the architecture and the different code elements to the packaging is described in the following section. == Layers +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The package structure of your code inside `src/main/java` (and `src/test/java`) of your app is described in our coding conventions in the sections link:coding-conventions.asciidoc#packages[packages]. The following table describes our classic approach for packaging and layering: @@ -60,6 +66,8 @@ The following table describes our classic approach for packaging and layering: == Architecture Mapping +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In order to help you to map the architecture, packaging, layering, etc. to the code and see where different code elements should be placed, we provide this architecture mapping: diff --git a/documentation/guide-structure-modern.asciidoc b/documentation/guide-structure-modern.asciidoc index 7c55f5dc..786bd41d 100644 --- a/documentation/guide-structure-modern.asciidoc +++ b/documentation/guide-structure-modern.asciidoc @@ -1,17 +1,17 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Modern project structure +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + With trends such as cloud, microservices, lean, and agile, we decided for a more modern project structure that fits better to recent market trends. When starting new projects with devonfw, and especially in the context of cloud-native development, we strongly recommend this modern approach over the link:guide-structure-classic.asciidoc[classic structure]. == Modules +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Due to trends such as microservices, we are building smaller apps compared to moduliths. For simplicity, we therefore do not split our app into different modules and keep everything top-level and easy. @@ -33,6 +33,8 @@ In addition to `java` and `resources`, we also add `helm` for helm templates and == Deployment +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For modern projects, we strongly recommend that your build process generates the final deliverable as an OCI compliant container. Further, to go fully cloud-native, you should build your app as a native image via https://www.graalvm.org/[GraalVM] AOT compiler. Therefore, we recommed to use https://quarkus.io/[quarkus] as your main framework. @@ -40,6 +42,8 @@ In case you want to go with spring, you may consider using https://github.com/sp == Layers +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The package structure of your code inside `src/main/java` (and `src/test/java`) of your app is described in our coding conventions in the sections link:coding-conventions.asciidoc#packages[packages]. For the modern project structure, the layers are defined by the following table: @@ -54,6 +58,8 @@ For the modern project structure, the layers are defined by the following table: == Architecture Mapping +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In order to help you to map the architecture, packaging, layering, etc. to the code and see where different code elements should be placed, we provide this architecture mapping: diff --git a/documentation/guide-structure.asciidoc b/documentation/guide-structure.asciidoc index f03f3623..d48038a9 100644 --- a/documentation/guide-structure.asciidoc +++ b/documentation/guide-structure.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Project structure +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In devonfw we want to give clear structure and guidance for building applications. This also allows tools such as https://github.com/devonfw/cobigen[CobiGen] or https://github.com/devonfw/sonar-devon4j-plugin/[sonar-devon4j-plugin] to "understand" the code. Also this helps developers going from one devonfw project to the next one to quickly understand the code-base. diff --git a/documentation/guide-testing-snapshots.asciidoc b/documentation/guide-testing-snapshots.asciidoc index 0334a45c..4ae96c24 100644 --- a/documentation/guide-testing-snapshots.asciidoc +++ b/documentation/guide-testing-snapshots.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Testing devon4j SNAPSHOT releases +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Whenever a story in devon4j is completed by merging a https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests[PR], our https://github.com/features/actions[github actions] will build a new SNAPSHOT release and on success deploy it to nexus on OSSRH. You can therefore find the latest devonfw SNAPSHOT releases https://oss.sonatype.org/content/repositories/snapshots/com/devonfw/[here]. diff --git a/documentation/guide-testing.asciidoc b/documentation/guide-testing.asciidoc index 2df59cec..88488849 100644 --- a/documentation/guide-testing.asciidoc +++ b/documentation/guide-testing.asciidoc @@ -1,13 +1,13 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Testing +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == General best practices + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For testing please follow our general best practices: * Tests should have a clear goal that should also be documented. @@ -28,6 +28,8 @@ For testing please follow our general best practices: * Prefer delegation over inheritance for cross-cutting testing functionality. Good places to put this kind of code can be realized and reused via the JUnit +@Rule+ mechanism. == Test Automation Technology Stack + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For test automation we use http://junit.org/[JUnit]. However, we are strictly doing all assertions with http://joel-costigliola.github.io/assertj/[AssertJ]. For xref:test-doubles[mocking] we use http://mockito.org/[Mockito]. In order to mock remote connections we use xref:wiremock[WireMock]. @@ -36,6 +38,8 @@ For testing entire components or sub-systems we recommend to use for Spring stac In case you have to use a full blown JEE application server, we recommend to use http://arquillian.org/[arquillian]. To get started with arquillian, look http://arquillian.org/guides/getting_started/index.html#add_the_arquillian_apis[here]. == Test Doubles + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We use http://xunitpatterns.com/Using%20Test%20Doubles.html[test doubles] as generic term for mocks, stubs, fakes, dummies, or spys to avoid confusion. Here is a short summary from http://martinfowler.com/articles/mocksArentStubs.html[stubs VS mocks]: * **Dummy** objects specifying no logic at all. May declare data in a POJO style to be used as boiler plate code to parameter lists or even influence the control flow towards the test's needs. @@ -46,6 +50,8 @@ We use http://xunitpatterns.com/Using%20Test%20Doubles.html[test doubles] as gen We try to give some examples, which should make it somehow clearer: === Stubs + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Best Practices for applications: * A good way to replace small to medium large boundary systems, whose impact (e.g. latency) should be ignored during load and performance tests of the application under development. @@ -53,6 +59,8 @@ Best Practices for applications: * Do NOT use stubs as basis of a large amount of test cases as due to state-based verification of stubs, test developers will enrich the stub implementation to become a large monster with its own hunger after maintenance efforts. === Mocks + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Best Practices for applications: * Replace not-needed dependencies of your system-under-test (SUT) to minimize the application context to start of your component framework. @@ -60,6 +68,8 @@ Best Practices for applications: * Remember: Not everything has to be mocked! Especially on lower levels of tests like isolated module tests you can be betrayed into a mocking delusion, where you end up in a hundred lines of code mocking the whole context and five lines executing the test and verifying the mocks behavior. Always keep in mind the benefit-cost ratio, when implementing tests using mocks. === WireMock + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. //Wiremock is not used in the current Application If you need to mock remote connections such as HTTP-Servers, WireMock offers easy to use functionality. For a full description see the http://wiremock.org/[homepage] or the https://github.com/tomakehurst/wiremock[github repository]. Wiremock can be used either as a JUnit Rule, in Java outside of JUnit or as a standalone process. The mocked server can be configured to respond to specific requests in a given way via a fluent Java API, JSON files and JSON over HTTP. An example as an integration to JUnit can look as follows. [source,java] @@ -107,6 +117,8 @@ public void faultTest() { A GET request to `../fault` returns an OK status header, then garbage, and then closes the connection. == Integration Levels + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. There are many discussions about the right level of integration for test automation. Sometimes it is better to focus on small, isolated modules of the system - whatever a "module" may be. In other cases it makes more sense to test integrated groups of modules. Because there is no universal answer to this question, devonfw only defines a common terminology for what could be tested. Each project must make its own decision where to put the focus of test automation. There is no worldwide accepted terminology for the integration levels of testing. In general we consider http://istqbexamcertification.com/what-are-software-testing-levels/[ISTQB]. However, with a technical focus on test automation we want to get more precise. The following picture shows a simplified view of an application based on the link:architecture.asciidoc#technical-architecture[devonfw reference architecture]. We define four integration levels that are explained in detail below. @@ -123,6 +135,8 @@ External systems do not belong to any of the integration levels defined here. de The following chapters describe the four integration levels. === Level 1 Module Test + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The goal of a _isolated module test_ is to provide fast feedback to the developer. Consequently, isolated module tests must not have any interaction with the client, the database, the file system, the network, etc. An isolated module test is testing a single classes or at least a small set of classes in isolation. If such classes depend on other components or external resources, etc. these shall be replaced with a xref:test-doubles[test double]. @@ -149,6 +163,8 @@ For an advanced example see https://github.com/devonfw/devon4j/blob/develop/modu === Level 2 Component Test +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + A http://istqbexamcertification.com/what-is-component-testing/[_component test_] aims to test components or component parts as a unit. These tests can access resources such as a database (e.g. for DAO tests). Further, no remote communication is intended here. Access to external systems shall be replaced by a xref:test-doubles[test double]. @@ -196,6 +212,8 @@ public class UcFindCountryTest { When you are testing use-cases your link:guide-access-control.asciidoc#configuration-on-java-method-level[authorization] will also be in place. Therefore, you have to simulate a logon in advance what is done via the `login` method in the above Spring example. The test-infrastructure will automatically do a `logout` for you after each test method in `doTearDown`. === Level 3 Subsystem Test + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A _subsystem test_ runs against the external interfaces (e.g. HTTP service) of the integrated subsystem. Subsystem tests of the client subsystem are described in the link:https://github.com/devonfw/devon4ng/blob/master/documentation/guide-testing.asciidoc[devon4ng testing guide]. In devon4j the server (JEE application) is the subsystem under test. The tests act as a client (e.g. service consumer) and the server has to be integrated and started in a container. * With devon4j and Spring you can write a subsystem-test as easy as illustrated in the following example: @@ -230,17 +248,23 @@ Even though not obvious on the first look this test will start your entire appli Do not confuse a _subsystem test_ with a http://istqbexamcertification.com/what-is-system-integration-testing/[system integration test]. A system integration test validates the interaction of several systems where we do not recommend test automation. === Level 4 System Test + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A http://istqbexamcertification.com/what-is-system-testing/[_system test_] has the goal to test the system as a whole against its official interfaces such as its UI or batches. The system itself runs as a separate process in a way close to a regular deployment. Only external systems are simulated by xref:test-doubles[test doubles]. The devonfw only gives advice for automated system test (TODO see allure testing framework). In nearly every project there must be manual system tests, too. This manual system tests are out of scope here. === Classifying Integration-Levels + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For Spring stack, devon4j defines https://github.com/devonfw/devon4j/tree/develop/modules/test/src/main/java/com/devonfw/module/test/common/api/category[Category-Interfaces] that shall be used as https://github.com/junit-team/junit/wiki/Categories[JUnit Categories]. Also devon4j provides https://github.com/devonfw/devon4j/tree/develop/modules/test/src/main/java/com/devonfw/module/test/common/base[abstract base classes] that you may extend in your test-cases if you like. devon4j further pre-configures the maven build to only run integration levels 1-2 by default (e.g. for fast feedback in continuous integration). It offers the profiles +subsystemtest+ (1-3) and +systemtest+ (1-4). In your nightly build you can simply add +-Psystemtest+ to run all tests. == Implementation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. This section introduces how to implement tests on the different levels with the given devonfw infrastructure and the proposed frameworks. For Spring, see link:spring/guide-spring-testing.asciidoc#implementation[Spring Test Implementation] @@ -248,11 +272,15 @@ For Spring, see link:spring/guide-spring-testing.asciidoc#implementation[Spring == Regression testing +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + When it comes to complex output (even binary) that you want to regression test by comparing with an expected result, you sould consider https://approvaltests.com/[Approval Tests] using https://github.com/approvals/approvaltests.java[ApprovalTests.Java]. If applied for the right problems, it can be very helpful. == Deployment Pipeline +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + A deployment pipeline is a semi-automated process that gets software-changes from version control into production. It contains several validation steps, e.g. automated tests of all integration levels. Because devon4j should fit to different project types - from agile to waterfall - it does not define a standard deployment pipeline. But we recommend to define such a deployment pipeline explicitly for each project and to find the right place in it for each type of test. @@ -261,15 +289,21 @@ For that purpose, it is advisable to have fast running test suite that gives as Note, that the deployment pipeline always should contain manual validation steps, at least manual acceptance testing. There also may be manual validation steps that have to be executed for special changes only, e.g. usability testing. Management and execution processes of those manual validation steps are currently not in the scope of devonfw. == Test Coverage + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We are using tools (SonarQube/Jacoco) to measure the coverage of the tests. Please always keep in mind that the only reliable message of a code coverage of +X%+ is that +(100-X)%+ of the code is entirely untested. It does not say anything about the quality of the tests or the software though it often relates to it. == Test Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. This section covers test configuration in general without focusing on integration levels as in the first chapter. * For Spring, see link:spring/guide-spring-testing.asciidoc#configure-test-specific-beans[Configure Test Specific Beans] * For Quarkus, see link:quarkus/guide-quarkus-testing.asciidoc#configuration[here] === Configure Test Specific Beans + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Sometimes it can become handy to provide other or differently configured bean implementations via CDI than those available in production. For example, when creating beans using `@Bean`-annotated methods they are usually configured within those methods. https://github.com/devonfw/my-thai-star/blob/develop/java/mtsj/core/src/main/java/com/devonfw/application/mtsj/general/service/impl/config/WebSecurityBeansConfig.java[WebSecurityBeansConfig] shows an example of such methods. [source,java] @@ -316,15 +350,23 @@ The following http://docs.spring.io/spring/docs/current/spring-framework-referen === Test Data + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. It is possible to obtain test data in two different ways depending on your test's integration level. == Debugging Tests + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The following two sections describe two debugging approaches for tests. Tests are either run from within the IDE or from the command line using Maven. === Debugging with the IDE + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Debugging with the IDE is as easy as always. Even if you want to execute a `SubsystemTest` which needs a Spring context and a server infrastructure to run properly, you just set your breakpoints and click on Debug As -> JUnit Test. The test infrastructure will take care of initializing the necessary infrastructure - if everything is configured properly. === Debugging with Maven + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Please refer to the following two links to find a guide for debugging tests when running them from Maven. * http://maven.apache.org/surefire/maven-surefire-plugin/examples/debugging.html diff --git a/documentation/guide-text-search.asciidoc b/documentation/guide-text-search.asciidoc index c39dfe1e..8ad11a4b 100644 --- a/documentation/guide-text-search.asciidoc +++ b/documentation/guide-text-search.asciidoc @@ -1,16 +1,16 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Full Text Search +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + If you want to all your users fast and simple searches with just a single search field (like in google), you need full text indexing and search support. == Solutions +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + * http://lucene.apache.org/[Lucene] * https://lucene.apache.org/core/4_4_0/analyzers-common/org/apache/lucene/analysis/ngram/NGramTokenizer.html[NGram] * http://lucene.apache.org/solr/[Solr] @@ -23,4 +23,6 @@ Maybe you also want to use native features of your database == Best Practices +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + TODO \ No newline at end of file diff --git a/documentation/guide-transactions.asciidoc b/documentation/guide-transactions.asciidoc index 3741dfa9..0bb2c630 100644 --- a/documentation/guide-transactions.asciidoc +++ b/documentation/guide-transactions.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Transaction Handling +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For transaction handling we link:guide-aop.asciidoc[AOP] to add transaction control via annotations as aspect. This is done by annotating your code with the `@Transactional` annotation. You can either annotate your link:guide-dependency-injection.asciidoc#key-principles[container bean] at class level to make all methods transactional or your can annotate individual methods to make them transactional: @@ -20,6 +18,8 @@ You can either annotate your link:guide-dependency-injection.asciidoc#key-princi ---- == JTA Imports + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Here are the import statements for transaction support: [source, java] ---- @@ -29,6 +29,8 @@ import javax.transaction.Transactional; CAUTION: Use the above import statement to follow JEE and avoid using `org.springframework.transaction.annotation.Transactional`. == JTA Dependencies + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Please note that with https://jakarta.ee/[Jakarta EE] the dependencies have changed. When you want to start with Jakarta EE you should use these dependencies to get the annoations for dependency injection: @@ -54,6 +56,8 @@ The above Jakarate EE dependencies replace these JEE depdencies: ---- == Handling constraint violations + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Using `@Transactional` magically wraps transaction handling around your code. As constraints are checked by the database at the end when the transaction gets committed, a constraint violation will be thrown by this aspect outside your code. In case you have to handle constraint violations manually, you have to do that in code outside the logic that is annotated with `@Transactional`. @@ -61,4 +65,6 @@ This may be done in a link:guide-service-layer.asciidoc[service operation] by ca As a generic approach you can solve this via link:guide-rest.asciidoc#rest-exception-handling[REST execption handling]. == Batches + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Transaction control for batches is a lot more complicated and is described in the link:guide-batch-layer.asciidoc[batch layer]. \ No newline at end of file diff --git a/documentation/guide-transferobject.asciidoc b/documentation/guide-transferobject.asciidoc index 9e80c532..5badbe58 100644 --- a/documentation/guide-transferobject.asciidoc +++ b/documentation/guide-transferobject.asciidoc @@ -1,13 +1,9 @@ :toc: macro toc::[] - - -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Transfer-Objects +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The technical data model is defined in form of link:guide-jpa.asciidoc#entity[persistent entities]. However, passing persistent entities via _call-by-reference_ across the entire application will soon cause problems: diff --git a/documentation/guide-usecase.asciidoc b/documentation/guide-usecase.asciidoc index 208200dd..58c97354 100644 --- a/documentation/guide-usecase.asciidoc +++ b/documentation/guide-usecase.asciidoc @@ -1,11 +1,9 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = UseCase + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A use-case is a small unit of the link:guide-logic-layer.asciidoc[logic layer] responsible for an operation on a particular link:guide-jpa.asciidoc#entity[entity] (business object). We leave it up to you to decide whether you want to define an interface (API) for each use-case or provide an implementation directly. @@ -15,6 +13,8 @@ For https://en.wikipedia.org/wiki/Create,_read,_update_and_delete[CRUD] we use t In our example, we choose to define an interface for each use-case. We also use `*To` to refer to any type of transfer object. Please follow our link:guide-transferobject.asciidoc[guide] to understand more about different types of transfer object e.g. Eto, Dto, Cto == Find + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The `UcFind«BusinessObject»` defines all read operations to retrieve and search the `«BusinessObject»`. Here is an example: [source,java] @@ -26,6 +26,8 @@ public interface UcFindBooking { ---- == Manage + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The `UcManage«BusinessObject»` defines all CRUD write operations (create, update and delete) for the `«BusinessObject»`. Here is an example: [source,java] @@ -41,6 +43,8 @@ public interface UcManageBooking { ---- == Custom + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Any other non CRUD operation `Uc«Operation»«BusinessObject»` uses any other custom verb for `«Operation»`. Typically, such custom use-cases only define a single method. Here is an example: @@ -55,6 +59,8 @@ public interface UcApproveBooking { ---- == Implementation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The implementation should carry its own name and the suffix `Impl` and is annotated with `@Named` and `@ApplicationScoped`. It will need access to the persistent data which is done by injecting the corresponding repository (or DAO). Furthermore, it shall not expose persistent entities from the data access layer and has to map them to transfer objects using the bean-mapper. Please refer to our link:guide-beanmapping.asciidoc[bean mapping], link:guide-transferobject.asciidoc[transfer object] and link:guide-dependency-injection.asciidoc[dependency injection] documentation for more information. Here is an example: [source,java] @@ -95,6 +101,8 @@ public class BookingmanagementRestServiceImpl implements BookingmanagementRestSe ---- == Internal use case + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Sometimes, a component with multiple related entities and many use-cases needs to reuse business logic internally. Of course, this can be exposed as an official use-case API but this will imply using transfer-objects (ETOs) instead of entities. In some cases, this is undesired e.g. for better performance to prevent unnecessary mapping of entire collections of entities. In the first place, you should try to use abstract base implementations providing reusable methods the actual use-case implementations can inherit from. diff --git a/documentation/guide-validation.asciidoc b/documentation/guide-validation.asciidoc index 79f72600..192ce241 100644 --- a/documentation/guide-validation.asciidoc +++ b/documentation/guide-validation.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Validation +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Validation is about checking syntax and semantics of input data. Invalid data is rejected by the application. Therefore validation is required in multiple places of an application. E.g. the link:guide-client-layer.asciidoc[GUI] will do validation for usability reasons to assist the user, early feedback and to prevent unnecessary server requests. On the server-side validation has to be done for consistency and link:guide-security.asciidoc[security]. @@ -17,12 +15,16 @@ In general we distinguish these forms of validation: * _stateful validation_ is dependent on other states and can consider the same input data as valid in once case and as invalid in another. == Stateless Validation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For regular, stateless validation we use the JSR303 standard that is also called bean validation (BV). Details can be found in the http://beanvalidation.org/1.1/spec/[specification]. As implementation we recommend http://hibernate.org/validator/[hibernate-validator]. === Example +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + A description of how to enable BV for spring applications can be found in the relevant http://docs.spring.io/spring-framework/docs/current/spring-framework-reference/htmlsingle/#validation-beanvalidation[Spring documentation]. A guide you can use to integrate validation in Quarkus applications can be found https://quarkus.io/guides/validation[here]. For a quick summary follow these steps: * Make sure that hibernate-validator is located in the classpath by adding a dependency to the pom.xml. @@ -89,9 +91,13 @@ A list with all bean validation constraint annotations available for hibernate-v NOTE: **Bean Validation in Wildfly >v8:** Wildfly v8 is the first version of Wildfly implementing the JEE7 specification. It comes with bean validation based on https://samaxes.com/2014/04/jaxrs-beanvalidation-javaee7-wildfly/[hibernate-validator out of the box]. In case someone is running Spring in Wildfly for whatever reasons, the spring based annotation @Validated would duplicate bean validation at runtime and thus should be omitted. === GUI-Integration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. TODO === Cross-Field Validation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. BV has poor support for this. Best practice is to create and use beans for ranges, etc. that solve this. A bean for a range could look like so: [source,java] @@ -119,6 +125,8 @@ public class Range> { ---- == Stateful Validation + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For complex and stateful business validations we do not use BV (possible with groups and context, etc.) but follow KISS and just implement this on the server in a straight forward manner. An example is the deletion of a table in the example application. Here the state of the table must be checked first: diff --git a/documentation/guide-xml.asciidoc b/documentation/guide-xml.asciidoc index d93013fb..50089f66 100644 --- a/documentation/guide-xml.asciidoc +++ b/documentation/guide-xml.asciidoc @@ -1,27 +1,33 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = XML +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + http://en.wikipedia.org/wiki/XML[XML] (Extensible Markup Language) is a W3C standard format for structured information. It has a large eco-system of additional standards and tools. In Java there are many different APIs and frameworks for accessing, producing and processing XML. For the devonfw we recommend to use xref:jaxb[JAXB] for mapping Java objects to XML and vice-versa. Further there is the popular http://docs.oracle.com/javase/7/docs/api/org/w3c/dom/package-summary.html[DOM API] for reading and writing smaller XML documents directly. When processing large XML documents http://en.wikipedia.org/wiki/StAX[StAX] is the right choice. == JAXB + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We use http://en.wikipedia.org/wiki/Java_Architecture_for_XML_Binding[JAXB] to serialize Java objects to XML or vice-versa. === JAXB and Inheritance + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Use `@XmlSeeAlso` annotation to provide sub-classes. See section "Collective Polymorphism" described https://dzone.com/articles/java-and-xml-part-3-jaxb[here]. === JAXB Custom Mapping + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In order to map custom link:guide-datatype.asciidoc[datatypes] or other types that do not follow the Java bean conventions, you need to define a custom mapping. If you create dedicated objects for the XML mapping you can easily avoid such situations. When this is not suitable use `@XmlJavaTypeAdapter` and provide an `XmlAdapter` implementation that handles the mapping. For details see https://www.eclipse.org/eclipselink/documentation/2.6/moxy/advanced_concepts006.htm[here]. == Security +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To prevent XML External Entity attacks, follow https://docs.oracle.com/en/java/javase/11/security/java-api-xml-processing-jaxp-security-guide.html[JAXP Security Guide] and enable https://docs.oracle.com/en/java/javase/11/security/java-api-xml-processing-jaxp-security-guide.html#GUID-88B04BE2-35EF-4F61-B4FA-57A0E9102342[FSP]. diff --git a/documentation/performance-comparision-spring-quarkus.asciidoc b/documentation/performance-comparision-spring-quarkus.asciidoc index 033badcd..95cb35d4 100644 --- a/documentation/performance-comparision-spring-quarkus.asciidoc +++ b/documentation/performance-comparision-spring-quarkus.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Performance comparison between Spring and Quarkus +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus offers a big advantage in resource consumption compared to a Spring application. Especially in native mode, the memory footprint of a Quarkus application is extremely low, which can be a deciding factor in real-world environments. The tables <> and <>, which show the startup and memory consumption of two applications that are similar in their Quarkus and Spring implementations, illustrate this point. Application 1 is more complex in scope than Application 2 and uses more dependencies. The listings above the tables show the functions/extensions of the applications and the lines of code (only java files). diff --git a/documentation/quarkus.asciidoc b/documentation/quarkus.asciidoc index 8543ec74..3ca59c98 100644 --- a/documentation/quarkus.asciidoc +++ b/documentation/quarkus.asciidoc @@ -1,18 +1,18 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Quarkus +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + https://quarkus.io[Quarkus] is a Java framework for building cloud-native apps. It is fully supported by https://devonfw.com[devonfw] as an option and alternative to link:spring.asciidoc[spring]. Additional things like extensions will be available on the https://github.com/devonfw/devon4quarkus[devon4quarkus] GitHub repository. == Guide to the Reader +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Depending on your intention of reading this document, you might be more interested in the following chapters: * If you are completely new to Quarkus, you may be interested in the link:quarkus.asciidoc#pros[pros] and link:quarkus.asciidoc#cons[cons] of Quarkus. Also, take a look at the https://quarkus.io[official Quarkus website]. You might also be interested in the features that https://www.graalvm.org/[GraalVM] offers. @@ -34,6 +34,8 @@ Depending on your intention of reading this document, you might be more interest [[pros]] == Pros +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus offers the following benefits: * *fast turn-around cycles for developers* + @@ -46,6 +48,8 @@ As quarkus was born as a cloud-native framework, it is very light-weight and doe [[cons]] == Cons +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus has the following drawbacks: * *less flexible* + diff --git a/documentation/quarkus/getting-started-for-spring-developers.asciidoc b/documentation/quarkus/getting-started-for-spring-developers.asciidoc index 25e3e113..49074c06 100644 --- a/documentation/quarkus/getting-started-for-spring-developers.asciidoc +++ b/documentation/quarkus/getting-started-for-spring-developers.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Getting started with Quarkus for Spring developers +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + As a Spring developer, you have heard more and more about Quarkus: its pros and cons, its fast growth etc. So, you decided to adopt/try Quarkus for your (next) project(s) and are wondering where to go next and what you need to pay attention to when moving from Spring to Quarkus. This guide tries to address this exact concern. In the following, we will present you some main points you should be aware of when starting to develop with Quarkus, along with some useful sources. diff --git a/documentation/quarkus/getting-started-quarkus.asciidoc b/documentation/quarkus/getting-started-quarkus.asciidoc index 88945fcc..aefd7d46 100644 --- a/documentation/quarkus/getting-started-quarkus.asciidoc +++ b/documentation/quarkus/getting-started-quarkus.asciidoc @@ -1,14 +1,14 @@ -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Quarkus Quickstart +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This guide serves as a quickstart on how to create a Quarkus app, briefly presenting the key functionalities that Quarkus provides, both for beginners and experienced developers. == Introduction to Quarkus +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To get a first introduction to Quarkus, you can read the link:../quarkus.asciidoc[Quarkus introduction guide]. To get a brief overview of where you can find the important Quarkus related guides, follow the chapter link:../quarkus.asciidoc#guide-to-the-reader[guide to the reader]. Also, see the comparison of the link:../quarkus.asciidoc#Pros[advantages] and link:../quarkus.asciidoc#cons[disadvantages] of a Quarkus application compared to the alternative framework Spring. This comparison will be supported by our link:../performance-comparison-spring-quarkus.asciidoc[performance comparison between Spring and Quarkus], which demonstrates the lower resource consumption and startup time of Quarkus applications. @@ -16,6 +16,8 @@ This comparison will be supported by our link:../performance-comparison-spring-q == Installation of Tools and Dependencies +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + First, we need to install some dependencies and tools before we can start programming. Our tool https://devonfw.com/website/pages/docs/devonfw-ide-introduction.asciidoc.html[devonfw-ide] comes with many development tools for you. We need to install the following tools for this guide: @@ -44,6 +46,8 @@ We will create the project there. == Bootstrap a Quarkus Project +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus provides multiple ways to bootstrap a project. The option to bootstrap a project via the command-line is shown in the Quarkus getting started guide https://quarkus.io/guides/getting-started#bootstrapping-the-project[Bootstrap the project]. Quarkus also provides a project builder where you can select some extensions, the build tool for your project, and if you want, some starter code. @@ -51,16 +55,24 @@ This will deliver a project skeleton with the configured project dependencies an [NOTE] ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. By creating a Quarkus project from the command-line or with the project builder, you get a different project structure and have to adapt it to the devon4j conventions shown in the next Chapter. ==== +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Project Structure +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We provide a recommendation and guideline for a link:../guide-structure-modern.asciidoc[modern project structure] to help organize your project into logically related modules. In order to comply with the requirements of modern cloud development and microservice architectures, follow the guide and apply the modern project structure to your project. You can also find similar modules in our example projects. == Introduction to Quarkus Functionality + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Before we start programming, you should first have a look at the functionality of Quarkus. .Quarkus functionality guides @@ -73,6 +85,8 @@ This guide shows how to link:../guide-migration-spring-quarkus.asciidoc[migrate == Create a REST service + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Now let's create our first REST CRUD service with Quarkus. We give you the options of using a guide to start to code the service yourself or to just download a service that's ready to use. @@ -90,6 +104,8 @@ This project will be steadily improved and is used to showcase the abilities of == OpenAPI generation +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We provide a guide with a short introduction to the link:../guide-openaoi.asciidoc[OpenAPI specification] with two plugins that are important in a Quarkus Context. 1. link:../guide-openaoi.asciidoc#smallrye-openapi[Smallrye Openapi supported by quarkus] @@ -99,6 +115,8 @@ A more detailed usage guide to the Smallrye Plugin is provided by https://quarku == How to Integrate a Database + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The next step for our REST service would be to integrate a database to store the objects of the entity. With Quarkus, adding a database can be easy, because Quarkus can take over the build-up and connection process. @@ -132,9 +150,13 @@ The implementation is not our first choice with devon4j and therefore not part o [NOTE] ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. You need an installed Docker version for the https://quarkus.io/guides/datasource#dev-services[zero config setup]. ==== +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + .Database Migration For schema-based databases, we recommend migrating databases with Flyway. @@ -145,6 +167,8 @@ This should be used if you start your own database and do not leave the creation == Testing a Quarkus Application + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. After we have built the service, we have to verify it with some tests. We will give you some guidelines to implement some test cases. @@ -159,6 +183,8 @@ Most of the Quarkus applications are already equipped with a basic test and our == Packaging of a Quarkus application and creation of a native executable + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Quarkus applications can be packaged into different file types. The following link will show you how to build them and give you a short explanation of the characteristics of these files. .Package types @@ -174,6 +200,8 @@ Configure the Output with these https://quarkus.io/guides/maven-tooling#configur == Create and build a Docker Image +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus supports Jib, S2I and https://www.docker.com/[Docker] for building images. We focus on building a Quarkus App with Docker. You get a generated Dockerfile from Quarkus in the src/main/docker folder of any project generated from Quarkus. There are multiple Dockerfiles. @@ -189,8 +217,12 @@ The native file will run in a **Distroless container**. Distroless images are ve [Note] ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For more information to the different executables go back to the chapter xref:packaging-of-a-quarkus-application-and-creation-of-a-native-executable[Packaging of a Quarkus application and creation of a native executable] ==== + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. To simply build and run a Docker image, you can follow the instructions Quarkus provides for every Dockerfile in the comments block. Docker commands example for the JVM Dockerfile from our https://github.com/devonfw-sample/devon4quarkus-reference[reference project] diff --git a/documentation/quarkus/guide-authentication-quarkus.asciidoc b/documentation/quarkus/guide-authentication-quarkus.asciidoc index a5e68f34..b91d0d38 100644 --- a/documentation/quarkus/guide-authentication-quarkus.asciidoc +++ b/documentation/quarkus/guide-authentication-quarkus.asciidoc @@ -1,11 +1,9 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Quarkus Authentication + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Quarkus supports different authentication mechanisms through different extensions. For example: * https://quarkus.io/guides/security-properties[`quarkus-elytron-security-properties-file`] provides support for simple properties files that can be used for testing security. This supports both embedding user information in `application.properties` and standalone properties files. diff --git a/documentation/quarkus/guide-beanmapping-quarkus.asciidoc b/documentation/quarkus/guide-beanmapping-quarkus.asciidoc index fec65fd8..64301a51 100644 --- a/documentation/quarkus/guide-beanmapping-quarkus.asciidoc +++ b/documentation/quarkus/guide-beanmapping-quarkus.asciidoc @@ -1,18 +1,18 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Bean mapping with Quarkus +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This guide will show bean-mapping, in particular for a Quarkus application. We recommend using https://mapstruct.org/[MapStruct] with a Quarkus application because the other bean-mapper frameworks use Java reflections. They are not supported in GraalVm right now and cause problems when building native applications. MapStruct is a code generator that greatly simplifies the implementation of mappings between Java bean types based on a convention over configuration approach. The mapping code will be generated at compile-time and uses plain method invocations and is thus fast, type-safe, and easy to understand. MapStruct has to be configured to not use Java reflections, which will be shown in this guide. You can find the official https://mapstruct.org/documentation/stable/reference/pdf/mapstruct-reference-guide.pdf[MapStruct reference guide] and a general introduction to MapStruct from https://www.baeldung.com/mapstruct[Baeldung]. == MapStruct Dependency + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. To get access to MapStruct, we have to add the dependency to our POM.xml: [source, xml] @@ -52,9 +52,13 @@ MapStruct takes advantage of generated getters, setters, and constructors from t == MapStruct Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We already discussed the benefits of https://github.com/devonfw/devon4j/blob/master/documentation/guide-dependency-injection.asciidoc#dependency-injection[dependency injection]. MapStruct supports CDI with EJB, spring, and jsr330. The default retrieving method for a mapper is a factory that uses reflections, which should be avoided. The component model should be set to CDI, as this will allow us to easily inject the generated mapper implementation. The component model can be configured in multiple ways. === Simple Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Add the attribute *componentModel* to the *@Mapper* annotation in the mapper interface. [source, java] ---- @@ -65,6 +69,8 @@ public interface ProductMapper{ ---- === MapperConfig Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Create a shared configuration that can be used for multiple mappers. Implement an interface and use the annotation *@MapperConfig* for the class. You can define all configurations in this interface and pass the generated `MapperConfig.class` with the *config* attribute to the mapper. The `MapperConfig` also defines the *InjectionStrategy* and *MappingInheritaceStrategy*, both of which will be explained later. A list of all configurations can be found https://mapstruct.org/documentation/stable/api/org/mapstruct/MapperConfig.html[here]. [source, java] @@ -88,6 +94,8 @@ public interface ProductMapper{ Any attributes not given via *@Mapper* will be inherited from the shared configuration `MapperConfig.class`. === Configuration via annotation processor options + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The MapStruct code generator can be configured using annotation processor options. You can pass the options to the compiler while invoking javac directly, or add the parameters to the maven configuration in the POM.xml @@ -102,6 +110,8 @@ A list of all annotation processor options can be found https://mapstruct.org/do == Basic Bean-Mapper Usage +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To use the mapper, we have to implement the mapper interface and the function prototypes with a *@Mapper* annotation. [source, java] ---- @@ -132,6 +142,8 @@ That is the basic usage of a Mapstruct mapper. In the next chapter, we'll go int == Advanced Bean-Mapper Usage +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Let´s assume that our `Product` entity and the `ProductDto` have some differently named properties that should be mapped. Add a mapping annotation to map the property *type* from `Product` to *kind* from `ProductDto`. We define the source name of the property and the target name. [source, java] diff --git a/documentation/quarkus/guide-exception-handling.asciidoc b/documentation/quarkus/guide-exception-handling.asciidoc index dc51b05c..bc522cad 100644 --- a/documentation/quarkus/guide-exception-handling.asciidoc +++ b/documentation/quarkus/guide-exception-handling.asciidoc @@ -1,18 +1,18 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Exception Handling in Quarkus +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For link:../guide-exceptions.asciidoc[handling exceptions] within a Spring application, devon4j provides the https://github.com/devonfw/devon4j/tree/master/modules/rest[devon4j-rest module], which provides a https://github.com/devonfw/devon4j/blob/develop/modules/rest/src/main/java/com/devonfw/module/rest/service/impl/RestServiceExceptionFacade.java[`RestServiceExceptionFacade`] to handle all exceptions in a consistent way. Since the module is not suitable for Quarkus, we need to implement this ourselves. This guide shows how to do just that. For an example, see our https://github.com/devonfw-sample/devon4quarkus-reference[Quarkus reference application]. == Exception mapping +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We suggest to implement the exception handling the https://quarkus.io/specs/jaxrs/2.1/index.html#exceptionmapper[JAX-RS way] using `ExceptionMapper`. RESTEasy provides several https://github.com/quarkusio/quarkus/tree/main/extensions/resteasy-classic/resteasy/runtime/src/main/java/io/quarkus/resteasy/runtime[exception mappers] out of the box. For example, RESTEasy's https://github.com/quarkusio/quarkus/blob/main/extensions/resteasy-classic/resteasy/runtime/src/main/java/io/quarkus/resteasy/runtime/NotFoundExceptionMapper.java[`NotFoundExceptionMapper`] provides a web page that shows all available endpoints in dev mode. diff --git a/documentation/quarkus/guide-native-image.asciidoc b/documentation/quarkus/guide-native-image.asciidoc index 4e3a2089..67050df0 100644 --- a/documentation/quarkus/guide-native-image.asciidoc +++ b/documentation/quarkus/guide-native-image.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Building a native image +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus provides the ability to create a native executable of the application called _https://quarkus.io/guides/building-native-image[native image]_. Unlike other Java based deployments, a native image will only run on the architecture and operating system it is compiled for. Also, no JVM is needed to run the native-image. @@ -18,21 +16,29 @@ To build your quarkus app as a native-image, you have two options that are descr == Build a native executable with GraalVM +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To build a Quarkus application, you can install GraalVM locally on your machine, as described below. Therefore, read the link:quarkus-template.asciidoc#basic-templates[basic Quarkus application chapter], or clone the https://github.com/devonfw-sample/devon4quarkus-reference[example project] provided by devonfw. Follow this https://quarkus.io/guides/building-native-image#producing-a-native-executable[chapter] from the Quarkus Guide for building a native executable. === Installing GraalVM +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + A native image can be created locally or through a container environment. To create a native image locally, an installed and configured version of GraalVM is needed. You can follow the https://quarkus.io/guides/building-native-image#prerequisites-for-oracle-graalvm-ceee[installation guide from Quarkus] or the https://www.graalvm.org/docs/getting-started/#install-graalvm[guide provided by GraalVM] for this. == Build a native executable with GraalVM through container environment +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In order to make the build of native images more portable, you can also use your container environment and run the GraalVM inside a container (typically Docker). You can simply install Docker with your devonfw-ide distribution, just follow this description link:https://github.com/devonfw/ide/blob/master/documentation/docker.asciidoc[Docker with devonfw-ide]. Follow this https://quarkus.io/guides/building-native-image#container-runtime[chapter] to build a native Linux image through container runtime. == Configuring the native executable +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + A list of all configuration properties for a native image can be found https://quarkus.io/guides/building-native-image#configuration-reference[here]. diff --git a/documentation/quarkus/guide-quarkus-configuration.asciidoc b/documentation/quarkus/guide-quarkus-configuration.asciidoc index 5981667a..d0a699ae 100644 --- a/documentation/quarkus/guide-quarkus-configuration.asciidoc +++ b/documentation/quarkus/guide-quarkus-configuration.asciidoc @@ -1,18 +1,20 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + link:quarkus.asciidoc[Quarkus] provides a comprehensive guide on configuration https://quarkus.io/guides/config-reference[here]. == External Application Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Database Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In Quarkus, Hibernate is provided by the `quarkus-hibernate-orm` extension. Ensure the extension is added to your `pom.xml` as follows: [source,xml] @@ -26,6 +28,8 @@ In Quarkus, Hibernate is provided by the `quarkus-hibernate-orm` extension. Ensu Additionally, you have to add the respective JDBC driver extension to your `pom.xml`. There are different drivers for different database types. See https://quarkus.io/guides/hibernate-orm#setting-up-and-configuring-hibernate-orm[Quarkus Hibernate guide]. === Database System and Access + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. You need to configure which database type you want to use, as well as the location and credentials to access it. The defaults are configured in `application.properties`. The file should therefore contain the properties as in the given example: [source, properties] @@ -40,6 +44,8 @@ quarkus.hibernate-orm.database.generation=drop-and-create ---- === Database Logging + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Add the following properties to `application.properties` to enable logging of database queries for debugging purposes. [source, properties] @@ -53,8 +59,12 @@ quarkus.hibernate-orm.log.bind-parameters=true == Secrets and environment specific configurations +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Environment variables +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + There are also some libraries to make Jasypt work with Quarkus, such as https://camel.apache.org/camel-quarkus/latest/reference/extensions/jasypt.html[Camel Quarkus Jasypt]. Unfortunately, this feature only works in JVM mode and not in native mode. Quarkus supports many credential providers with official extensions, such as HashiCorp Vault. @@ -74,11 +84,15 @@ When using Kubernetes, the secrets can be stored as __Kubernetes secret__ and th === Custom config sources +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus provides the possability to add custom config sources, which can be used to retrieve configuration values from custom locations. For a description of this feature, see the link:https://quarkus.io/guides/config-extending-support#custom-config-source[corresponding Quarkus guide]. ==== Config interceptors +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Quarkus also allows with the concept of interceptors to hook into the resolution of configuration values. This can be useful when configuration values are encrypted or need to be extracted. To do this, you have to implement a `ConfigSourceInterceptor`. @@ -110,6 +124,8 @@ To use the Interceptor, you must register it. To do this, create a file `io.sma === Credential encryption +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + As for link:../spring/guide-spring-configuration.asciidoc#security[Spring], there are also some libraries that let Jasypt work with Quarkus such as https://camel.apache.org/camel-quarkus/latest/reference/extensions/jasypt.html[Camel Quarkus Jasypt]. Unfortunately, this feature only works in JVM mode and not in native mode, so it is not a suitable approach. If you want to store usernames or passwords in encrypted form or retrieve them from a custom store, you can use a custom `CredentialsProvider` for this purpose. @@ -137,6 +153,8 @@ For more information about the credentials provider, see the official link:https === HashiCorp Vault +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For centralized management of secrets and other critical configuration values, you can use link:https://www.vaultproject.io/[HashiCorp Vault] as external management tool. For detailed instructions on how to integrate Vault into your Quarkus application, see the official link:https://quarkus.io/guides/vault[Quarkus guide]. diff --git a/documentation/quarkus/guide-quarkus-testing.asciidoc b/documentation/quarkus/guide-quarkus-testing.asciidoc index e2a98518..2fb7db97 100644 --- a/documentation/quarkus/guide-quarkus-testing.asciidoc +++ b/documentation/quarkus/guide-quarkus-testing.asciidoc @@ -1,13 +1,13 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Testing +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Quarkus relies on JUnit for testing. [source, xml] ---- @@ -26,6 +26,8 @@ quarkus.http.test-ssl-port=8446 Quarkus supports injecting scoped CDI beans into your tests via `@Inject` annotation for e.g. unit testing or beans testing. === Mocking CDI beans + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The `io.quarkus.test.junit.QuarkusMock` class can be used to temporarily mock out any normal scoped bean (e.g. @ApplicationScoped, @RequestScoped etc, basically every scope except @Singleton and @Dependent). If you use this method in a `@BeforeAll`, the mock will take effect for all tests on the current class, while if you use this in a test method, the mock will only take effect there. An example is given below: [source, java] ---- @@ -87,9 +89,13 @@ public class MockTestCase { } ---- === Test profiles + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Quarkus supports testing different configurations with test profiles. A test profile has to implement the `QuarkusTestProfile` . To write a profile, please follow https://quarkus.io/guides/getting-started-testing#writing-a-profile[this guide]. === Continuous testing + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. By design, Quarkus enables test-driven development. It detects affected tests as changes are made and automatically rerun them in background. As that, it gives developer instant feedback. To use continuous testing, execute the following command: [source, shell script] ---- @@ -99,4 +105,6 @@ mvn quarkus:dev For more details, see https://quarkus.io/guides/continuous-testing[here]. === Native testing + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. It's possible to test native executables using `@NativeImageTest` (which might be replaced by @QuarkusIntergrationTest in the future). For more, see https://quarkus.io/guides/getting-started-testing#native-executable-testing[here]. diff --git a/documentation/quarkus/quarkus-template.asciidoc b/documentation/quarkus/quarkus-template.asciidoc index dbb2cf12..2fd4953c 100644 --- a/documentation/quarkus/quarkus-template.asciidoc +++ b/documentation/quarkus/quarkus-template.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Quarkus template +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + https://code.quarkus.io/?g=org.devonfw&e=resteasy&e=resteasy-jackson&e=hibernate-validator&e=hibernate-orm&e=micrometer[Quarkus Code Generator] is provides many alternative technologies and libraries that can be integrated into a project. Detailed guides on multiple topics can be found https://quarkus.io/guides/[here]. Due to the large selection, getting started can be difficult for developers. @@ -17,6 +15,8 @@ With that said, please take this as a recommendation and not as a compulsion. De If you are new to Quarkus, consider checking out their https://quarkus.io/guides/getting-started[getting started guide] to get an overview of how to create, run, test, as well as package a Quarkus application. Another recommended source to get started is https://www.katacoda.com/openshift/courses/developing-with-quarkus/getting-started[the Katacoda tutorials]. === Basic templates + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. [start=1] . simple REST API (https://code.quarkus.io/?g=com.devonfw&e=resteasy&e=resteasy-jackson&e=hibernate-validator&e=hibernate-orm[go to code.quarkus.io]) . simple REST API with monitoring (https://code.quarkus.io/?g=com.devonfw&e=resteasy&e=resteasy-jackson&e=hibernate-validator&e=hibernate-orm&e=micrometer&e=smallrye-health[go to code.quarkus.io]) diff --git a/documentation/spring.asciidoc b/documentation/spring.asciidoc index a5529417..76693830 100644 --- a/documentation/spring.asciidoc +++ b/documentation/spring.asciidoc @@ -1,17 +1,17 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Spring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + https://spring.io[Spring] is the most famous and established Java framework. It is fully supported by https://devonfw.com[devonfw] as an option and alternative to link:quarkus.asciidoc[quarkus]. == Guide to the Reader +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Dependent on the intention you are reading this document, you might be most interested in the following chapters: * If you are not yet familiar with Spring, you may be interested in xref:pros[pros] and xref:cons[cons] of Spring. Also take a look at the link:https://spring.io/why-spring[official Spring website]. @@ -25,6 +25,8 @@ Dependent on the intention you are reading this document, you might be most inte [[pros]] == Pros +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Spring offers the following benefits: * *highly flexible* + @@ -39,6 +41,8 @@ See https://spring.io/why-spring[Why Spring?] for details. [[cons]] == Cons +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Spring has the following drawbacks: * *history and legacy* + @@ -48,10 +52,14 @@ While for the last decades spring was leading innovation in Java app development == Spring-Boot +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + https://spring.io/projects/spring-boot[Spring-boot] is a project and initiaitve within the spring-ecosystem that brought a lot of innovation and simplification into app development on top of spring. As of today we typically use the terms _spring_ and _spring-boot_ rather synonymously as we always use spring together with spring-boot. == Spring-Native +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + https://github.com/spring-projects-experimental/spring-native[Spring-native] adds cloud-native support to the spring ecosystem and allows to build a spring app as cloud-native image via https://www.graalvm.org/[GraalVM]. You may also consider link:quarkus.asciidoc[Quarkus] if you are interested in building cloud-native images. For a comparison of both Spring Native and Quarkus, you may refer to our link:Spring-native-vs-Quarkus.asciidoc[Spring Native vs. Quarkus] guide. diff --git a/documentation/spring/guide-authentication-spring.asciidoc b/documentation/spring/guide-authentication-spring.asciidoc index d09a76b0..37451562 100644 --- a/documentation/spring/guide-authentication-spring.asciidoc +++ b/documentation/spring/guide-authentication-spring.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Spring Security +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We use https://projects.spring.io/spring-security/[spring-security] as a framework for authentication purposes. Therefore, you need to provide an implementation of https://docs.spring.io/spring-security/site/docs/4.2.x/apidocs/org/springframework/security/config/annotation/web/WebSecurityConfigurer.html[WebSecurityConfigurerAdapter]: @@ -40,6 +38,8 @@ Mix authentication should be avoided where possible. However, when needed, you c https://docs.spring.io/spring-security/site/docs/current/reference/htmlsingle/#multiple-httpsecurity[here]. === Preserve original request anchors after form login redirect + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Spring Security will automatically redirect any unauthorized access to the defined login-page. After successful login, the user will be redirected to the original requested URL. The only pitfall is, that anchors in the request URL will not be transmitted to server and thus cannot be restored after successful login. Therefore the `devon4j-security` module provides the `RetainAnchorFilter`, which is able to inject javascript code to the source page and to the target page of any redirection. Using javascript this filter is able to retrieve the requested anchors and store them into a cookie. Heading the target URL this cookie will be used to restore the original anchors again. To enable this mechanism you have to integrate the `RetainAnchorFilter` as follows: diff --git a/documentation/spring/guide-beanmapping-spring.asciidoc b/documentation/spring/guide-beanmapping-spring.asciidoc index 402eca22..61ae12d5 100644 --- a/documentation/spring/guide-beanmapping-spring.asciidoc +++ b/documentation/spring/guide-beanmapping-spring.asciidoc @@ -1,17 +1,15 @@ - - -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Bean Mapping in devon4j-spring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We have developed a solution that uses a `BeanMapper` that allows to abstract from the underlying implementation. As mentioned in the link:../guide-beanmapping.asccidoc[general bean mapping guide], we started with http://dozer.sourceforge.net/documentation/about.html[Dozer] a Java Bean to Java Bean mapper that recursively copies data from one object to another. Now we recommend using https://orika-mapper.github.io/orika-docs/[Orika]. This guide will show an introduction to Orika and Dozer bean-mapper. == Bean-Mapper Dependency +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To get access to the `BeanMapper` we have to use either of the below dependency in our POM: .*Orika* @@ -35,8 +33,12 @@ To get access to the `BeanMapper` we have to use either of the below dependency ---- == Bean-Mapper Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. === Bean-Mapper Configuration using Dozer +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The `BeanMapper` implementation is based on an existing open-source bean-mapping framework. In case of Dozer the mapping is configured `src/main/resources/config/app/common/dozer-mapping.xml`. @@ -56,6 +58,8 @@ Important is that you configure all your custom datatypes as ` @@ -24,6 +24,8 @@ The repository must extend https://github.com/devonfw/devon4j/blob/develop/modul -------- == Example + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The following example shows how to write such a repository. The example has the same functionality as the example in the link:../guide-repository.asciidoc#example[Spring Data guide]: [source,java] @@ -52,9 +54,13 @@ public interface ExampleRepository extends DefaultRepository { ---- == Further examples + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. You can also read the JUnit test-case https://github.com/devonfw/devon4j/blob/develop/starters/starter-spring-data-jpa/src/test/java/com/devonfw/module/jpa/dataaccess/api/DefaultRepositoryTest.java[DefaultRepositoryTest] that is testing an example https://github.com/devonfw/devon4j/blob/develop/starters/starter-spring-data-jpa/src/test/java/com/devonfw/example/component/dataaccess/api/FooRepository.java[FooRepository]. == Auditing + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In case you need link:../guide-auditing.asciidoc[auditing], you only need to extend `DefaultRevisionedRepository` instead of `DefaultRepository`. The auditing methods can be found in https://github.com/devonfw/devon4j/blob/develop/modules/jpa-spring-data/src/main/java/com/devonfw/module/jpa/dataaccess/api/data/GenericRevisionedRepository.java[GenericRevisionedRepository]. diff --git a/documentation/spring/guide-jwt-spring.asciidoc b/documentation/spring/guide-jwt-spring.asciidoc index 693a8a00..d73e0ba3 100644 --- a/documentation/spring/guide-jwt-spring.asciidoc +++ b/documentation/spring/guide-jwt-spring.asciidoc @@ -1,14 +1,14 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = JWT Spring-Starter +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == Keystore +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + A KeyStore is a repository of certificates and keys (public key, private key, or secret key). They can be used for TSL transportation, for encryption and decryption as well as for signing. For demonstration you might create a keystore with openssl, with the following commands: @@ -27,6 +27,8 @@ NOTE: Please use reasonable passwords instead of `password` what should be obvio == JWT Dependency +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To use JWT support from devon4j with spring-boot you have to add following required dependency: [source,xml] @@ -39,6 +41,8 @@ To use JWT support from devon4j with spring-boot you have to add following requi == Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The following properties need to be configured in your `application.properties` file: [source,properties] @@ -71,6 +75,8 @@ See also https://github.com/devonfw/devon4j/blob/master/modules/security-jwt/src == Authentication with JWT via OAuth +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The authentication with JWT via OAuth (HTTP header), will happen via `JwtAuthenticationFilter` that is automatically added by `devon4j-starter-security-jwt` via `JwtAutoConfiguration`. With the starter and auto-configuration we want to make it as easy as possible for you. In case you would like to build a server app that e.g. wants to issue JWTs but does not allow authentication via JWT itself, you can use `devon4j-security-jwt` as dependency instead of the starter and do the spring config yourself (pick and choose from `JwtAutoConfiguration`). @@ -94,6 +100,8 @@ To do this, you need to add the following changes in your `BaseWebSecurityConfig == Login with Username and Password to get JWT +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To allow a client to login with username and password to get a JWT for sub-sequent requests, you need to do the following changes in your `BaseWebSecurityConfig`: [source,java] @@ -118,4 +126,6 @@ To allow a client to login with username and password to get a JWT for sub-seque == Authentication with Kafka +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Authentication with JWT and Kafka is explained in the link:guide-kafka.asciidoc[Kafka guide]. diff --git a/documentation/spring/guide-kafka-spring.asciidoc b/documentation/spring/guide-kafka-spring.asciidoc index 233e8f79..1355f598 100644 --- a/documentation/spring/guide-kafka-spring.asciidoc +++ b/documentation/spring/guide-kafka-spring.asciidoc @@ -1,12 +1,10 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Kafka +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This guide explains how Spring Kafka is used in devonfw applications. It focuses on aspects which are special to devonfw if you want to learn about spring-kafka you should adhere to springs references documentation. There is an example of simple Kafka implementation in the https://github.com/devonfw-sample/devon4j-kafka-employeeapp[devon4j-kafka-employeeapp]. @@ -21,6 +19,8 @@ The devon4j-kafka library consists of: == How to use? +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To use devon4j-kafka you have to add required starter dependencies which is "starter-kafka-sender" or "starter-kafka-receiver" from devon4j. These 2 starters are responsible for taking care of the required spring configuration. If you only want to produce messages "starter-kafka-sender" is enough. For consuming messages you need "starter-kafka-receiver" which also includes "starter-kafka-sender". To use devon4j-kafka message sender add the below dependency: @@ -47,6 +47,8 @@ To use the devon4j-kafka message receiver configurations, loggers and message re == Property Parameters +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + As written before kafka-producer and listener-specific configuration is done via properties classes. These classes provide useful defaults, at a minimum the following parameters have to be configured: [source,properties] @@ -82,6 +84,8 @@ We use the same properties defined by Apache Kafka or Spring Kafka. They are sim == Naming convention for topics +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For better managing of several Kafka topics in your application portfolio we strongly advice to introduce a naming scheme for your topics. The schema may depend on the actual usage pattern of Kafka. For context where Kafka is used in a 1-to-1-communication-scheme (not publish/subscribe) the following schema has been proven useful in practice: @@ -94,6 +98,8 @@ To keep things easy and prevent problems we suggest to use only small letters, h == Send Messages +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + As mentioned above the 'starter-kafka-sender' is required to be added as a dependency to use MessageSender from Kafka. [source,xml] @@ -125,6 +131,8 @@ Example: There are multiple methods available from MessageSender of devon4j-kafka. The ProducerListener will log the message sent to the Kafka broker. == Receive Messages + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. To receive messages you have to define a listener. The listener is normally part of the service layer. [[img-t-architecture]] @@ -174,6 +182,8 @@ The other ack-mode values can be referred from https://docs.spring.io/spring-kafka/api/org/springframework/kafka/listener/ContainerProperties.AckMode.html[here]. == Retry + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The retry pattern in devon4j-kafka is invoked when a particular exception(described by user in application.properties file) is thrown while processing the consumed message and it is configured in application.properties file. The general idea is to separate messages which could not be processed into dedicated retry-topics to allow fine control on how processing of the messages is retried and to not block newly arriving messages. Let us see more about handling retry in the below topics. @@ -181,6 +191,8 @@ image::../images/kafka-retry.png["Retry pattern in devon4j-kafka",scaledwidth="8 === Handling retry in devon4j-kafka +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The retry pattern is included in the starter dependency of "starter-kafka-receiver". The retryPattern method is used by calling the method processMessageWithRetry(ConsumerRecord consumerRecord,MessageProcessor processor). Please find the below Example: @@ -223,6 +235,8 @@ It works as follows: compaction which is explained below. === Retry configuration and naming convention of redelivery topics. + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The following properties should be added in the `application.properties` or `application.yml` file. The retry pattern in devon4j-kafka will perform for specific topic of a message. So its mandatory to specify the properties for each topic. Below properties are example, @@ -292,18 +306,24 @@ The naming convention for retry topic is the same topic name which you have give If there is no topic found in the consumed record the default retry topic will be added which is `default-message-retry`. === Retry topics + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Devon4j-kafka uses a separate retry topic for each topic where retries occur. By default this topic is named `-retry`. You may change this behavior by providing your own implementation for `DefaultKafkaRecordSupport` which is a default implementation from devon4j-kafka for `KafkaRecordSupport`. Devon4j-kafka enqueues a new message for each retry attempt. It is very important to configure your retry tropics with https://kafka.apache.org/documentation/#compaction[log compaction] enabled. More or less simplified, if log compaction is enabled Kafka keeps only one message per message key. Since each retry message has the same key, in fact only one message per retry attempt is stored. After the last retry attempt the message payload is removed from the message so, you do not keep unnecessary data in your topics. === Handling retry finally failed +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Per default when the retry fails with final attempt we just log the message and delete the payload of ProducerRecord which comes to proceed the retry pattern. You can change this behavior by providing the implementation class for the interface `MessageRetryHandler.java` which has two methods `retryTimeout` and `retryFailedFinal`. == Tracer + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. We leverage https://spring.io/projects/spring-cloud-sleuth[Spring Cloud Sleuth] for tracing in devon4j-kafka This is used to trace the asynchronous process of Kafka producing and consuming. In an asynchronous process it is important to maintain an id which will be same for all asynchronous process. However, devon uses its own correlation-id(UUID) to track the process. But devon4j-kafka uses an additional tracing protocol which is https://github.com/openzipkin/brave[Brave Tracer]. @@ -315,6 +335,8 @@ The trace-id is same for all the asynchronous process and span-id is unique for === How devon4j-kafka handles tracer ? +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + We inject the trace-id and span-id in to the ProducerRecord headers which comes to publish into the Kafka broker. It's injected in the headers with the key `traceId` for trace-id and `spanId` for span-id. Along with these, the correlation-id(UUID) is also injected in the headers of record with the key `correlationId`. @@ -324,6 +346,8 @@ So, when you consume record from Kafka broker, these values can be found in the So, it is very helpful to track the asynchronous process of consuming the messages. == Logging + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. devon4j-kafka provides multiple support classes to log the published message and the consumed message. * The class `ProducerLoggingListener` which implements ProducerListener from Spring Kafka uses to log the message as soon as it is published in the Kafka broker. @@ -335,6 +359,8 @@ is used to listen to the classes which is annotated with `@KafkaListener` and lo * The class `LoggingErrorHandler` which implements `ErrorHandler` from spring-kafka which logs the message when an error occurred while consuming messages. You may change this behavior by creating your own implementation class for the ErrorHandler. == Kafka Health check using Spring acutator + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The spring config class MessageCommonConfig automatically provides a spring health indicator bean for kafka if the property endpoints. The health indicator will check for all topics listed in `messaging.kafka.health.topics-tocheck` if a leader is available. If this property is missing only the broker connection will be checked. The timeout for @@ -355,8 +381,12 @@ These properties are provided with default values except the topicsToCheck and h == Authentication +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === JSON Web Token (JWT) +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + devon4j-kafka supports authentication via JSON Web Tokens (JWT) out-of-the-box. To use it add a dependency to the devon4j-starter-security-jwt: @@ -385,6 +415,8 @@ To secure a message listener with jwt add the `@JwtAuthentication`: With this annotation in-place each message will be checked for a valid JWT in a message header with the name `Authorization`. If a valid annotation is found the spring security context will be initialized with the user roles and "normal" authorization e.g. with `@RolesAllowed` may be used. This is also demonstrated in the kafka sample application. == Using Kafka for internal parallel processing + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Apart from the use of Kafka as "communication channel", it is sometimes helpful to use Kafka internally to do parallel processing: .Architecture for internal parallel processing with Kafka diff --git a/documentation/spring/guide-querydsl-spring.asciidoc b/documentation/spring/guide-querydsl-spring.asciidoc index 043e5bd4..50bfebb5 100644 --- a/documentation/spring/guide-querydsl-spring.asciidoc +++ b/documentation/spring/guide-querydsl-spring.asciidoc @@ -1,16 +1,16 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = QueryDSL in devon4j-spring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To implement dynamic queries, devon4j suggests the use of QueryDSL. QueryDSL uses metaclasses generated from entity classes at build time. devon4j-spring provides a way to use QueryDSL without the need for code generation. For this, devon4j provides the interface https://github.com/devonfw/devon4j/blob/master/modules/jpa-spring-data/src/main/java/com/devonfw/module/jpa/dataaccess/api/data/DefaultRepository.java[DefaultRepository] that your repository needs to extend and the https://github.com/devonfw/devon4j/blob/master/modules/jpa-basic/src/main/java/com/devonfw/module/jpa/dataaccess/api/QueryUtil.java[QueryUtil] helper class to build your queries. == Example +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Here is an example for using QueryDSL in devon4j-spring: [source,java] @@ -40,6 +40,8 @@ Here is an example for using QueryDSL in devon4j-spring: == Pagination +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + Pagination for dynamic or generally handwritten queries is provided in devon4j-spring via https://github.com/devonfw/devon4j/blob/develop/modules/jpa-basic/src/main/java/com/devonfw/module/jpa/dataaccess/api/QueryUtil.java#L102[QueryUtil.findPaginated(...)]: [source,java] diff --git a/documentation/spring/guide-service-client-spring.asciidoc b/documentation/spring/guide-service-client-spring.asciidoc index 5f5eed41..208ea298 100644 --- a/documentation/spring/guide-service-client-spring.asciidoc +++ b/documentation/spring/guide-service-client-spring.asciidoc @@ -2,15 +2,15 @@ :icons: font toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Service Client in devon4j-spring +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + This guide is about consuming (calling) services from other applications (micro-services) in devon4j-spring. == Dependency + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. You need to add (at least one of) these dependencies to your application: [source,xml] -------- @@ -41,9 +41,13 @@ You need to add (at least one of) these dependencies to your application: -------- == Features + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. When invoking a service, you need to consider many cross-cutting aspects. You might not think about them in the very first place and you do not want to redundantly implement them multiple times. Therefore, you should consider using this approach. The following sub-sections list the covered features and aspects: === Simple usage + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Assuming you already have a Java interface `MyService` of the service you want to invoke: [source,java] @@ -98,6 +102,8 @@ As you can see, both synchronous and asynchronous invocation of a service is ver ==== Asynchronous Invocation of void Methods +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + If you want to call a service method with `void` as the return type, the type-safe `call` method cannot be used as `void` methods do not return a result. Therefore you can use the `callVoid` method as following: [source,java] @@ -114,6 +120,8 @@ If you want to call a service method with `void` as the return type, the type-sa You may also provide `null` as `resultHandler` for "fire and forget". However, this will lead to the result being ignored, so even in the case of an error you will not be notified. === Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. This solution allows a very flexible configuration on the following levels: 1. Global configuration (defaults) @@ -159,6 +167,8 @@ service.client.app.bar.auth=authForward ``` === Service Discovery + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. You do not want to hardwire service URLs in your code, right? Therefore, different strategies might apply to _discover_ the URL of the invoked service. This is done internally by an implementation of the interface `ServiceDiscoverer`. The default implementation simply reads the base URL from the configuration. @@ -183,6 +193,8 @@ As you can use any implementation of `ServiceDiscoverer`, you can also easily us However, we recommend to use https://istio.io/[istio] instead, as described below. === Headers + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A very common demand is to tweak (HTTP) headers in the request to invoke the service. May it be for security (authentication data) or for other cross-cutting concerns (such as the link:../guide-logging.asciidoc#correlation-id[Correlation ID]). This is done internally by implementations of the interface `ServiceHeaderCustomizer`. We already provide several implementations such as: @@ -194,9 +206,13 @@ We already provide several implementations such as: Additionally, you can add further custom implementations of `ServiceHeaderCustomizer` for your individual requirements and additional headers. === Timeouts + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. You can configure timeouts in a very flexible way. First of all, you can configure timeouts to establish the connection (`timeout.connection`) and to wait for the response (`timeout.response`) separately. These timeouts can be configured on all three levels as described in the configuration section above. === Error Handling + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Whilst invoking a remote service, an error may occur. This solution will automatically handle such errors and map them to a higher level `ServiceInvocationFailedException`. In general, we separate two different types of errors: * *Network error* + @@ -216,6 +232,8 @@ You may even provide your own implementation of `ServiceClientErrorFactory` inst ==== Handling Errors +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In case of a synchronous service invocation, an error will be immediately thrown so you can surround the call with a regular try-catch block: [source,java] @@ -261,12 +279,16 @@ If you are using asynchronous service invocation, an error can occurr in a separ The error handler consumes `Throwable`, and not only `RuntimeException`, so you can get notified even in case of an unexpected `OutOfMemoryError`, `NoClassDefFoundError`, or other technical problems. Please note that the error handler may also be called from the thread calling the service (e.g. if already creating the request fails). The default error handler used if no custom handler is set will only log the error and do nothing else. === Logging + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. By default, this solution will log all invocations including the URL of the invoked service, success or error status flag and the duration in seconds (with decimal nano precision as available). Therefore, you can easily monitor the status and performance of the service invocations. Here is an example from our tests: ``` Invoking service com.devonfw.test.app.myexample.service.api.rest.MyExampleRestService#greet[http://localhost:50178/app/services/rest/my-example/v1/greet/John%20Doe%20%26%20%3F%23] took PT20.309756622S (20309756622ns) and succeded with status 200. ``` === Resilience + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Resilience adds a lot of complexity, which typically means that addressing this here would most probably result in not being up-to-date and not meeting all requirements. Therefore, we recommend something completely different: the _sidecar_ approach (based on https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar[sidecar pattern]). This means that you use a generic proxy app that runs as a separate process on the same host, VM, or container of your actual application. Then, in your app, you call the service via the sidecar proxy on `localhost` (service discovery URL is e.g. `http://localhost:8081/${app}/services/${type}`) that then acts as proxy to the actual remote service. Now aspects such as resilience with circuit breaking and the actual service discovery can be configured in the sidecar proxy app, independent of your actual application. Therefore, you can even share and reuse configuration and experience with such a sidecar proxy app even across different technologies (Java, .NET/C#, Node.JS, etc.). Further, you do not pollute the technology stack of your actual app with the infrastructure for resilience, throttling, etc. and can update the app and the sidecar independently when security-fixes are available. Various implementations of such sidecar proxy apps are available as free open source software. diff --git a/documentation/spring/guide-spring-configuration.asciidoc b/documentation/spring/guide-spring-configuration.asciidoc index 33e22d8a..7d2391ce 100644 --- a/documentation/spring/guide-spring-configuration.asciidoc +++ b/documentation/spring/guide-spring-configuration.asciidoc @@ -1,16 +1,18 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == Internal Application Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. There usually is a main configuration registered with main Spring Boot App, but differing configurations to support automated test of the application can be defined using profiles (not detailed in this guide). === Spring Boot Application + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. For a complete documentation, see the http://docs.spring.io/spring-boot/docs/current-SNAPSHOT/reference/htmlsingle/[Spring Boot Reference Guide]. With spring-boot you provide a simple _main class_ (also called starter class) like this: @@ -41,6 +43,8 @@ If you want to map spring configuration properties into your custom code please === Standard beans configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + For basic bean configuration we rely on spring boot using mainly configuration classes and only occasionally XML configuration files. Some key principle to understand Spring Boot auto-configuration features: * Spring Boot auto-configuration attempts to automatically configure your Spring application based on the jar dependencies and annotated components found in your source code. @@ -55,9 +59,13 @@ More specific configuration files (as required) reside in an adequately named su `src/main/resources/app` === BeanMapper Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In case you are still using dozer, you will find further details in link:guide-beanmapping-spring.asciidoc#bean-mapper-configuration[bean-mapper configuration]. === Security configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. The abstract base class `BaseWebSecurityConfig` should be extended to configure web application security thoroughly. A basic and secure configuration is provided which can be overridden or extended by subclasses. Subclasses must use the `@Profile` annotation to further discriminate between beans used in production and testing scenarios. See the following example: @@ -80,6 +88,8 @@ See https://github.com/devonfw/my-thai-star/blob/develop/java/mtsj/core/src/main === WebSocket configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. A websocket endpoint is configured within the business package as a Spring configuration class. The annotation `@EnableWebSocketMessageBroker` makes Spring Boot registering this endpoint. //Changed path due to non existent configuration in the example project [source, java] @@ -93,7 +103,11 @@ public class WebSocketConfig extends AbstractWebSocketMessageBrokerConfigurer { ---- == External Application Configuration + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. === application.properties files + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html[Here] is a list of common properties provided by the Spring framework. For a general understanding how spring-boot is loading and boostrapping your `application.properties` see https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html[spring-boot external configuration]. @@ -114,9 +128,13 @@ In this `application.properties` you only define the minimum properties that are === Database Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The configuration for spring and Hibernate is already provided by devonfw in our sample application and the application template. So you only need to worry about a few things to customize. ==== Database System and Access + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Obviously you need to configure which type of database you want to use as well as the location and credentials to access it. The defaults are configured in `application.properties` that is bundled and deployed with the release of the software. The files should therefore contain the properties as in the given example: [source, properties] @@ -133,6 +151,8 @@ For further details about `database.hibernate.hbm2ddl.auto` please see http://do If your application supports multiples database types, set `spring.profiles.active=XXX` in `src/main/resources/config/application.properties` choose database of your choice. Also, one has to set all the active spring profiles in this `application.properties` and not in any of the other `application.properties`. ==== Database Logging + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Add the following properties to `application.properties` to enable logging of database queries for debugging purposes. [source, properties] @@ -144,7 +164,11 @@ spring.jpa.properties.hibernate.format_sql=true == Security +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Password Encryption + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In order to support encrypted passwords in spring-boot `application.properties` all you need to do is to add https://github.com/ulisesbocchio/jasypt-spring-boot#jasypt-spring-boot[jasypt-spring-boot] as dependency in your `pom.xml` (please check for recent version link:https://mvnrepository.com/artifact/com.github.ulisesbocchio/jasypt-spring-boot-starter[here]): [source, xml] ---- diff --git a/documentation/spring/guide-spring-testing.asciidoc b/documentation/spring/guide-spring-testing.asciidoc index f8f903dc..9fe20968 100644 --- a/documentation/spring/guide-spring-testing.asciidoc +++ b/documentation/spring/guide-spring-testing.asciidoc @@ -1,15 +1,17 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Testing +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == Implementation +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Module Test + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. In devon4j you can extend the abstract class https://github.com/devonfw/devon4j/blob/develop/modules/test/src/main/java/com/devonfw/module/test/common/base/ModuleTest.java[ModuleTest] to basically get access to assertions. In order to test classes embedded in dependencies and external services one needs to provide mocks for that. As the xref:test-automation-technology-stack[technology stack] recommends we use the Mockito framework to offer this functionality. The following example shows how to implement Mockito into a JUnit test. //We currently don't use Mockito in the application [source,java] @@ -58,6 +60,8 @@ public StaffMemberEto findStaffMember(Long id) { In this simple example one has to stub two calls on the CUT as you can see below. For example the method call of the CUT `staffMemberDao.find(id)` is stubbed for returning a mock object `staffMemberEntity` that is also defined as mock. === Subsystem Test + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. devon4j provides a simple test infrastructure to aid with the implementation of subsystem tests. It becomes available by simply subclassing link:https://github.com/oasp/oasp4j/blob/master/samples/core/src/test/java/io/oasp/gastronomy/restaurant/general/common/base/AbstractRestServiceTest.java[AbstractRestServiceTest.java]. [source,java] ------------------------------------------- @@ -79,7 +83,11 @@ After the test method call one can verify the expected results. Mockito can chec == Configuration +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Configure Test Specific Beans + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. Sometimes it can become handy to provide other or differently configured bean implementations via CDI than those available in production. For example, when creating beans using `@Bean`-annotated methods they are usually configured within those methods. https://github.com/oasp/oasp4j/blob/master/samples/core/src/main/java/io/oasp/gastronomy/restaurant/general/service/impl/config/WebSecurityBeansConfig.java[WebSecurityBeansConfig] shows an example of such methods. [source,java] diff --git a/documentation/tutorial-newapp.asciidoc b/documentation/tutorial-newapp.asciidoc index 0d923708..1085938c 100644 --- a/documentation/tutorial-newapp.asciidoc +++ b/documentation/tutorial-newapp.asciidoc @@ -1,14 +1,14 @@ :toc: macro toc::[] -WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. - -''' - = Creating a new application +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + == Running the archetype +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + In order to create a new application you must use the archetype provided by devon4j which uses the maven archetype functionality. To create a new application, you should have installed devonfw IDE. Follow the devon ide documentation to install @@ -16,6 +16,8 @@ the same. You can choose between 2 alternatives, create it from command line or, in more visual manner, within eclipse. === From command Line + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. To create a new devon4j application from command line, you can simply run the following command: [source,bash] @@ -45,6 +47,8 @@ Further providing additional properties (using `-D` parameter) you can customize |======================= === From Eclipse + +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. After that, you should follow this Eclipse steps to create your application: * Create a new Maven Project. @@ -60,6 +64,8 @@ image::images/eclipse-m2e-create-devon4j-project-parameters.png["Configure arche == What is generated +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + The application template (archetype) generates a Maven multi-module project. It has the following modules: * `api`: module with the API (REST service interfaces, transferobjects, datatypes, etc.) to be imported by other apps as a maven dependency in order to invoke and consume the offered (micro)services. @@ -77,10 +83,16 @@ The toplevel `pom.xml` of the generated project has the following features: == How to run your app +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + === Run app from IDE +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + To run your application from your favourite IDE, simply launch `SpringBootApp` as java application. === Run app as bootified jar or war +WARNING: Hey there! Seems like you are still using the documentation of our legacy Java repository. Since it won't be maintained anymore, we recommend you to checkout the new Java page https://devonfw.com/docs/java/current/[here]. + More details are available link:guide-structure-classic.asciidoc#deployment[here].