Merge branch 'main' into docs/mscb-aura-styling

Author: sissbruecker

…ps/business-logic/add-service/index.adoc …ing-apps/business-logic/add-service.adocarticles/building-apps/business-logic/add-service/index.adoc renamed to articles/building-apps/business-logic/add-service.adoc articles/building-apps/business-logic/add-service/index.adoc renamed to articles/building-apps/business-logic/add-service.adoc

@@ -2,20 +2,19 @@
 title: Add a Service
 page-title: How to add an application service to a Vaadin application 
 description: Learn how to add an application service to a Vaadin application.
-meta-description: Learn how to design and implement application services in Vaadin. This guide covers best practices, security, naming conventions, and calling services from Flow and Hilla views.
-layout: tabbed-page
-tab-title: Overview
+meta-description: Learn how to design and implement application services in Vaadin. This guide covers best practices, security, naming conventions, and calling services from Vaadin views.
 order: 5
 ---
 
 
 = Add an Application Service
+:toclevels: 2
 
-In a Vaadin application, the _application layer_ contains the business, the data, and any integrations to external systems. The application layer exposes an <<../../architecture/api-spi#,API>> that the _UI layer_ (i.e., the views) can call:
+In a Vaadin application, the _application layer_ contains the business, the data, and any integrations to external systems. The application layer exposes an <<../architecture/api-spi#,API>> that the _UI layer_ (i.e., the views) can call:
 
 image::images/application-layer-api.png[A diagram of the UI layer calling the application layer through an API]
 
-This API is implemented by _application services_. In practice, application services are *Spring beans* that you can call from Vaadin Flow and Hilla views. 
+This API is implemented by _application services_. In practice, application services are *Spring beans* that you can call from Vaadin views. 
 
 
 == Design Guidelines
@@ -24,8 +23,8 @@ You can design application services according to your preferred architectural st
 
 * The application services should have *high cohesion*. This means that all the methods in your service should relate to the same thing.
 * The application services should be *stateless*.
-* Application services should *initiate and complete <<../../forms-data/consistency/transactions#,database transactions>>* before returning results.
-* The application services should be *<<../../security/protect-services#,secure>>*.
+* Application services should *initiate and complete <<../forms-data/consistency/transactions#,database transactions>>* before returning results.
+* The application services should be *<<../security/protect-services#,secure>>*.
 * Views should invoke application services, but application services *should not have dependencies on views*.
 
 [NOTE]
@@ -88,7 +87,7 @@ Vaadin does not enforce a specific naming convention for application services. W
 
 == Input & Output
 
-Application services often need to communicate with <<../../forms-data/repositories#,repositories>> to fetch and store data. They also need to pass this data to the UI layer. For this, there are two options: pass the entities directly; or pass Data Transfer Objects (DTO:s). Both have advantages and disadvantages.
+Application services often need to communicate with <<../forms-data/repositories#,repositories>> to fetch and store data. They also need to pass this data to the UI layer. For this, there are two options: pass the entities directly; or pass Data Transfer Objects (DTO:s). Both have advantages and disadvantages.
 
 
 === Entities
@@ -116,9 +115,6 @@ public class CustomerCrudService {
 }
 ----
 
-[CAUTION]
-When most of your service methods delegate to a repository, it may be tempting to skip the service and have the UI layer communicate directly with the repository. However, this isn't a good idea because of the cross-cutting concerns that the application service has to handle. This is explained later on this page.
-
 Using entities in your application service is a good idea when your user interface and entities match each other, closely. For example, you could have a form with fields that match the fields of the entity -- or a grid with columns that match them.
 
 Your entities should be _anemic_, which means that they only contain data and little to no business logic.
@@ -138,7 +134,7 @@ In this case, the application services should accept DTO:s as input, and return
 
 This adds another responsibility to the application service: mapping between entities and DTO:s.
 
-When using <<../../forms-data/repositories#query-classes,query classes>>, you can do the mapping in them by returning their DTO:s, directly. The query DTO:s become part of the application layer API.
+When using <<../forms-data/repositories#query-classes,query classes>>, you can do the mapping in them by returning their DTO:s, directly. The query DTO:s become part of the application layer API.
 
 For storing data, services typically have to copy data from the DTO to the entity. For example, like this:
 
@@ -176,14 +172,14 @@ When using DTO:s, you have more code to maintain. Some changes, like adding a ne
 
 === Domain Payload Objects
 
-When using <</building-apps/forms-data/consistency/domain-primitives#,domain primitives>>, you should use them in your DTO:s, as well. In this case, the DTO:s are called _Domain Payload Objects_ (DPO). They're used in the exact same way as DTO:s.
+When using <<../forms-data/consistency/domain-primitives#,domain primitives>>, you should use them in your DTO:s, as well. In this case, the DTO:s are called _Domain Payload Objects_ (DPO). They're used in the exact same way as DTO:s.
 
 
 === Validation
 
 All input should be validated by the application services before they do anything else with it. This is important for security, integrity, and consistency. Even if you use input validation in your user interface, you should still validate the data in the application services.
 
-You can validate the input in different ways. For more information, see the <</building-apps/forms-data/consistency/validation#,Validation>> documentation page.
+You can validate the input in different ways. For more information, see the <<../forms-data/consistency/validation#,Validation>> documentation page.
 
 
 == Package Naming
@@ -194,14 +190,169 @@ For example, services related to "customer relationship management" would be pla
 
 This structure keeps services well-organized, easy to find, and clearly associated with their purpose.
 
-See the <<../../architecture/packages#,Package Structure>> documentation page for more information.
+See the <<../architecture/packages#,Package Structure>> documentation page for more information.
+
+
+== Injecting a Service into a View
+
+Since application services are Spring beans, you can inject them directly into your Vaadin views through constructor injection.
+
+In the following example, [classname]`CustomerOnboardingService` is injected into [classname]`CustomerOnboardingView`:
+
+[source,java]
+----
+@Route
+public class CustomerOnboardingView extends Main {
+
+    private final CustomerOnboardingService service; // <1>
+
+// tag::snippet[]
+    public CustomerOnboardingView(CustomerOnboardingService service) { // <2>
+// end::snippet[]
+        this.service = service;
+        // ...
+    }
+    ...
+}
+----
+<1> Store the service in a `final` variable for future reference.
+<2> Inject the service as a constructor parameter.
+
+Constructor injection is recommended because it ensures that dependencies are provided at object creation, making the class easier to test and avoiding potential issues with uninitialized fields. Additionally, since the service is stored in a final variable, it cannot be reassigned accidentally, ensuring safer code.
+
+
+== Calling a Service
+
+Since Vaadin views are regular Java objects, calling a service is as simple as invoking a method.
+
+In the following example, the view calls [classname]`CustomerOnboardingService` when the user clicks a button:
+
+[source,java]
+----
+@Route
+public class CustomerOnboardingView extends Main {
+
+    private final CustomerOnboardingService service;
+    private final Binder<CustomerOnboardingForm> binder;
+
+    public CustomerOnboardingView(CustomerOnboardingService service) {
+        this.service = service;
+        this.binder = new Binder<>(CustomerOnboardingForm.class);
+
+        // Fields omitted
+
+        var createCustomerBtn = new Button("Create");
+// tag::snippet[]
+        createCustomerBtn.addClickListener(event -> createCustomer());
+// end::snippet[]
+        add(createCustomerBtn);
+    }
+    
+    private void createCustomer() {
+// tag::snippet[]
+        try {
+            var formData = binder.writeRecord(); // <1>
+            var customer = service.onboardCustomer(formData); // <2>
+            CustomerView.navigateTo(customer.customerId()); // <3>
+        } catch (ValidationException ex) {
+            // Handle the exception
+        }
+// end::snippet[]
+    }
+}
+----
+<1> Retrieves a `CustomerOnboardingForm` record from the binder.
+<2> Calls the service to onboard the customer.
+<3> Navigates to the newly created customer's view.
+
+For more information about forms and data binding, see the <<../forms-data/add-form#,Add a Form>> guide.
 
 
-== Calling from Views
+== Calling a Service on View Creation
 
-You can call an application service both from Flow and Hilla. When calling an application service from a Hilla view, it must be *browser-callable*, which introduces certain design constraints. These constraints do not apply when calling the service from a Flow view.
+Sometimes, you may need to call a service immediately upon view creation—for example, to populate a combo box or grid with data. While it may be tempting to do this in the constructor, *this is not recommended*.
 
-The following guides teach you how to call application services in Flow and Hilla:
+Vaadin may instantiate a view without actually displaying it. Because of this, you should *keep constructors free of side effects*.
+
+.What is a side effect?
+[NOTE]
+A _side effect_ is any operation that modifies state outside the object's scope or interacts with external systems like databases, files, or network services during object construction.
+
+
+=== After Navigation
+
+To call a service only after the user has navigated to a view, implement the [interfacename]`AfterNavigationObserver` interface and call the service in the [methodname]`afterNavigation()` method:
+
+[source,java]
+----
+@Route
+// tag::snippet[]
+public class MyView extends Main implements AfterNavigationObserver {
+// end::snippet[]
+
+    private final CountryService countryService;
+    private final ComboBox<Country> countries;
+
+    public MyView(CountryService countryService) {
+        this.countryService = countryService;
+        countries = new ComboBox<>();
+        add(countries);
+    }
+
+// tag::snippet[]
+    @Override
+    public void afterNavigation(AfterNavigationEvent afterNavigationEvent) {
+        countries.setItems(countryService.getCountries());
+    }
+// end::snippet[]
+}
+----
+
+This ensures that service calls happen only when the view is actually rendered.
+
+
+=== Cleaning Up
+
+If a service call requires cleanup afterward -- such as unsubscribing from a stream -- use Vaadin's *attach and detach events*.
+
+Every Vaadin component is notified when it is attached to or detached from the UI. You can handle these events in two ways:
+
+1. Override the protected [methodname]`onAttach()` and [methodname]`onDetach()` methods.
+2. Register attach and detach listeners dynamically.
+
+A common approach is to override [methodname]`onAttach()` and register a detach listener.
+
+In the following example, the view subscribes to a reactive stream when attached and unsubscribes when detached:
+
+[source,java]
+----
+public class MyView extends Main {
+
+    private final SubscriptionService subscriptionService;
+
+    public MyView(SubscriptionService subscriptionService) {
+        this.subscriptionService = subscriptionService;
+        // ...
+    }
+
+// tag::snippet[]
+    @Override
+    protected void onAttach(AttachEvent attachEvent) {
+        var subscription = subscriptionService.myStream().subscribe(message -> { // <1>
+            // Do something with the message
+        });
+        addDetachListener(detachEvent -> {
+            detachEvent.unregisterListener(); // <2>
+            subscription.dispose(); // <3>
+        });
+    }
+// end::snippet[]
+}
+----
+<1> Calls the service to subscribe to the stream when attached.
+<2> Removes the detach listener to prevent duplicate listeners.
+<3> Cancels the subscription to avoid memory leaks.
 
-* <<flow#,Calling Application Services in Flow>>
-* <<hilla#,Calling Application Services in Hilla>>
+.Components Can Be Attached and Detached Multiple Times
+[IMPORTANT]
+When adding a detach listener inside [methodname]`onAttach()`, always remove it when the component is detached. Otherwise, if the component is reattached later, multiple detach listeners will accumulate, leading to potential memory leaks.