Skip to content

Jafly. Notifications Core

Notifications Core

Send email, SMS, and push notifications through provider ports, with templates, preferences, and metrics.

Inject EmailService, SMSService, or PushService and supply the matching provider bean. Template email requires a NotificationTemplateEngine; the in-memory preference implementation is process-local and should be evaluated before using it for durable user preferences.

Maven artifact Packaging Source project
org.fireflyframework:fireflyframework-notifications-core jar modules/notifications/fireflyframework-notifications-core

Part of External services.

In the onboarding service

The onboarding service can use EmailService to confirm receipt or request missing information. The wiring recipe below registers the facade explicitly and keeps the provider behind EmailProvider.

Add the component

Installation and version availability explains source builds and published releases.

<dependency>
    <groupId>org.fireflyframework</groupId>
    <artifactId>fireflyframework-notifications-core</artifactId>
    <version>26.10.20-SNAPSHOT</version>
</dependency>

Quick start

The Java examples in this section are API fragments for application code. Use the stated imports and supply the application-owned collaborators described alongside them.

Choose the provider for the channel you need, then register that channel's service implementation explicitly. For example, the SendGrid adapter auto-configures an EmailProvider when selected and configured. It does not register EmailServiceImpl in an unrelated application's component-scan package.

For an application outside org.fireflyframework.notifications, place this application-owned configuration in a package scanned by Spring Boot:

import org.fireflyframework.notifications.core.services.email.v1.EmailServiceImpl;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;

@Configuration(proxyBeanMethods = false)
@Import(EmailServiceImpl.class)
class EmailNotificationsConfiguration {
}

Now inject the EmailService interface in application code. Do not scan every channel implementation when only one provider is configured; SMS and push services require their own provider beans.

import org.fireflyframework.notifications.core.services.email.v1.EmailService;
import org.fireflyframework.notifications.interfaces.dtos.email.v1.EmailRequestDTO;
import org.fireflyframework.notifications.interfaces.dtos.email.v1.EmailResponseDTO;
import reactor.core.publisher.Mono;

EmailRequestDTO request = EmailRequestDTO.builder()
        .from("orders@example.com")
        .to("customer@example.com")
        .subject("Your order")
        .text("Your order has been received.")
        .build();
Mono<EmailResponseDTO> result = emailService.sendEmail(request);

emailService is the injected bean; compose result into the application flow. A provider response is not proof of delivery to the recipient mailbox. Check the response status and the selected provider's error semantics.

Channel Service implementation to import Required provider
Email org.fireflyframework.notifications.core.services.email.v1.EmailServiceImpl EmailProvider
SMS org.fireflyframework.notifications.core.services.sms.v1.SMSServiceImpl SMSProvider
Push org.fireflyframework.notifications.core.services.push.v1.PushServiceImpl PushProvider

Template email additionally needs a NotificationTemplateEngine bean, for example new FreemarkerNotificationTemplateEngine() with templates under src/main/resources/notification-templates. A preference service must also be registered and invoked explicitly when the application applies user preferences; the in-memory implementation is process-local.

Configuration and wiring

This module declares no @ConfigurationProperties class of its own. Use the constructor/port contracts above and the configuration of the host or related core module.

Property-based wiring conditions found in this module:

Public API and extension points

Type Contract and responsibility
EmailService Sends email requests and template-email requests through the configured email provider.
SMSService Sends SMS requests through the configured SMS provider.
PushService Sends push-notification requests through the configured push provider.
NotificationTemplateEngine Renders the requested notification template with application-supplied variables.
NotificationPreferenceService Reads and updates the notification preferences used by the service layer.
Related component Why it belongs nearby
Notifications Library Group the notification service contracts and their core implementation.
Starter Core Assemble core infrastructure conventions for WebClient, actuator, logging, configuration, and service discovery.

Build and test

Use Java 25. From the repository root, build this component with its required dependencies:

git clone https://github.com/fireflyframework/fireflyframework-jafly.git
cd fireflyframework-jafly
./mvnw -pl :fireflyframework-notifications-core -am verify
./mvnw -pl :fireflyframework-notifications-core -am install

verify runs the selected projects' tests. install makes the current build available in your local Maven repository.

Representative test sources:

Mock, local-container, and application-context tests do not establish acceptance against a live provider account. Validate the intended provider deployment and credentials separately.

Test fixture

The sendEmail_returnsSuccess test demonstrates one concrete behavior. Excerpt from EmailServiceImplTest.java. The test class supplies its fixtures and imports.

@Test
void sendEmail_returnsSuccess() {
    EmailRequestDTO req = EmailRequestDTO.builder()
            .from("noreply@example.com")
            .to("user@example.com")
            .subject("Hello")
            .text("Hi")
            .build();

    EmailResponseDTO resp = emailService.sendEmail(req).block();
    assertThat(resp).isNotNull();
    assertThat(resp.getStatus()).isEqualTo(EmailStatusEnum.SENT);
    assertThat(resp.getMessageId()).isEqualTo("test-message-id");
}

Continue the application

Use the Notifications - SendGrid guide for the next part of this integration. The runnable submission/query service is in Getting started.

Source and further reading